1//! Definitions of a bunch of iterators for `[T]`.23#[macro_use] // import iterator! and forward_iterator!4mod macros;56use super::{from_raw_parts, from_raw_parts_mut};7use crate::hint::assert_unchecked;8use crate::iter::{9    FusedIterator, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce, UncheckedIterator,10};11use crate::marker::PhantomData;12use crate::mem::{self, SizedTypeProperties};13use crate::num::NonZero;14use crate::ptr::{NonNull, without_provenance, without_provenance_mut};15use crate::{cmp, fmt};1617#[stable(feature = "boxed_slice_into_iter", since = "1.80.0")]18impl<T> !Iterator for [T] {}1920#[stable(feature = "rust1", since = "1.0.0")]21impl<'a, T> IntoIterator for &'a [T] {22    type Item = &'a T;23    type IntoIter = Iter<'a, T>;2425    fn into_iter(self) -> Iter<'a, T> {26        self.iter()27    }28}2930#[stable(feature = "rust1", since = "1.0.0")]31impl<'a, T> IntoIterator for &'a mut [T] {32    type Item = &'a mut T;33    type IntoIter = IterMut<'a, T>;3435    fn into_iter(self) -> IterMut<'a, T> {36        self.iter_mut()37    }38}3940/// Immutable slice iterator41///42/// This struct is created by the [`iter`] method on [slices].43///44/// # Examples45///46/// Basic usage:47///48/// ```49/// // First, we need a slice to call the `iter` method on:50/// let slice = &[1, 2, 3];51///52/// // Then we call `iter` on the slice to get the `Iter` iterator,53/// // and iterate over it:54/// for element in slice.iter() {55///     println!("{element}");56/// }57///58/// // This for loop actually already works without calling `iter`:59/// for element in slice {60///     println!("{element}");61/// }62/// ```63///64/// [`iter`]: slice::iter65/// [slices]: slice66#[stable(feature = "rust1", since = "1.0.0")]67#[must_use = "iterators are lazy and do nothing unless consumed"]68#[rustc_diagnostic_item = "SliceIter"]69pub struct Iter<'a, T: 'a> {70    /// The pointer to the next element to return, or the past-the-end location71    /// if the iterator is empty.72    ///73    /// This address will be used for all ZST elements, never changed.74    ptr: NonNull<T>,75    /// For non-ZSTs, the non-null pointer to the past-the-end element.76    ///77    /// For ZSTs, this is `ptr::without_provenance_mut(len)`.78    end_or_len: *const T,79    _marker: PhantomData<&'a T>,80}8182#[stable(feature = "core_impl_debug", since = "1.9.0")]83impl<T: fmt::Debug> fmt::Debug for Iter<'_, T> {84    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {85        f.debug_tuple("Iter").field(&self.as_slice()).finish()86    }87}8889#[stable(feature = "rust1", since = "1.0.0")]90unsafe impl<T: Sync> Sync for Iter<'_, T> {}91#[stable(feature = "rust1", since = "1.0.0")]92unsafe impl<T: Sync> Send for Iter<'_, T> {}9394impl<'a, T> Iter<'a, T> {95    #[inline]96    pub(super) const fn new(slice: &'a [T]) -> Self {97        let len = slice.len();98        let ptr: NonNull<T> = NonNull::from_ref(slice).cast();99        // SAFETY: Similar to `IterMut::new`.100        unsafe {101            let end_or_len =102                if T::IS_ZST { without_provenance(len) } else { ptr.as_ptr().add(len) };103104            Self { ptr, end_or_len, _marker: PhantomData }105        }106    }107108    /// Views the underlying data as a subslice of the original data.109    ///110    /// # Examples111    ///112    /// Basic usage:113    ///114    /// ```115    /// // First, we need a slice to call the `iter` method on:116    /// let slice = &[1, 2, 3];117    ///118    /// // Then we call `iter` on the slice to get the `Iter` iterator:119    /// let mut iter = slice.iter();120    /// // Here `as_slice` still returns the whole slice, so this prints "[1, 2, 3]":121    /// println!("{:?}", iter.as_slice());122    ///123    /// // Now, we call the `next` method to remove the first element from the iterator:124    /// iter.next();125    /// // Here the iterator does not contain the first element of the slice any more,126    /// // so `as_slice` only returns the last two elements of the slice,127    /// // and so this prints "[2, 3]":128    /// println!("{:?}", iter.as_slice());129    ///130    /// // The underlying slice has not been modified and still contains three elements,131    /// // so this prints "[1, 2, 3]":132    /// println!("{:?}", slice);133    /// ```134    #[must_use]135    #[stable(feature = "iter_to_slice", since = "1.4.0")]136    #[inline]137    pub fn as_slice(&self) -> &'a [T] {138        self.make_slice()139    }140}141142iterator! {struct Iter -> *const T, &'a T, const, {/* no mut */}, as_ref, each_ref, {143    fn is_sorted_by<F>(self, mut compare: F) -> bool144    where145        Self: Sized,146        F: FnMut(&Self::Item, &Self::Item) -> bool,147    {148        self.as_slice().is_sorted_by(|a, b| compare(&a, &b))149    }150}}151152#[stable(feature = "rust1", since = "1.0.0")]153impl<T> Clone for Iter<'_, T> {154    #[inline]155    fn clone(&self) -> Self {156        Iter { ptr: self.ptr, end_or_len: self.end_or_len, _marker: self._marker }157    }158}159160#[stable(feature = "slice_iter_as_ref", since = "1.13.0")]161impl<T> AsRef<[T]> for Iter<'_, T> {162    #[inline]163    fn as_ref(&self) -> &[T] {164        self.as_slice()165    }166}167168/// Mutable slice iterator.169///170/// This struct is created by the [`iter_mut`] method on [slices].171///172/// # Examples173///174/// Basic usage:175///176/// ```177/// // First, we need a slice to call the `iter_mut` method on:178/// let slice = &mut [1, 2, 3];179///180/// // Then we call `iter_mut` on the slice to get the `IterMut` iterator,181/// // iterate over it and increment each element value:182/// for element in slice.iter_mut() {183///     *element += 1;184/// }185///186/// // We now have "[2, 3, 4]":187/// println!("{slice:?}");188/// ```189///190/// [`iter_mut`]: slice::iter_mut191/// [slices]: slice192#[stable(feature = "rust1", since = "1.0.0")]193#[must_use = "iterators are lazy and do nothing unless consumed"]194pub struct IterMut<'a, T: 'a> {195    /// The pointer to the next element to return, or the past-the-end location196    /// if the iterator is empty.197    ///198    /// This address will be used for all ZST elements, never changed.199    ptr: NonNull<T>,200    /// For non-ZSTs, the non-null pointer to the past-the-end element.201    ///202    /// For ZSTs, this is `ptr::without_provenance_mut(len)`.203    end_or_len: *mut T,204    _marker: PhantomData<&'a mut T>,205}206207#[stable(feature = "core_impl_debug", since = "1.9.0")]208impl<T: fmt::Debug> fmt::Debug for IterMut<'_, T> {209    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {210        f.debug_tuple("IterMut").field(&self.make_slice()).finish()211    }212}213214#[stable(feature = "rust1", since = "1.0.0")]215unsafe impl<T: Sync> Sync for IterMut<'_, T> {}216#[stable(feature = "rust1", since = "1.0.0")]217unsafe impl<T: Send> Send for IterMut<'_, T> {}218219impl<'a, T> IterMut<'a, T> {220    #[inline]221    pub(super) const fn new(slice: &'a mut [T]) -> Self {222        let len = slice.len();223        let ptr: NonNull<T> = NonNull::from_mut(slice).cast();224        // SAFETY: There are several things here:225        //226        // `ptr` has been obtained by `slice.as_ptr()` where `slice` is a valid227        // reference thus it is non-NUL and safe to use and pass to228        // `NonNull::new_unchecked` .229        //230        // Adding `slice.len()` to the starting pointer gives a pointer231        // at the end of `slice`. `end` will never be dereferenced, only checked232        // for direct pointer equality with `ptr` to check if the iterator is233        // done.234        //235        // In the case of a ZST, the end pointer is just the length.  It's never236        // used as a pointer at all, and thus it's fine to have no provenance.237        //238        // See the `next_unchecked!` and `is_empty!` macros as well as the239        // `post_inc_start` method for more information.240        unsafe {241            let end_or_len =242                if T::IS_ZST { without_provenance_mut(len) } else { ptr.as_ptr().add(len) };243244            Self { ptr, end_or_len, _marker: PhantomData }245        }246    }247248    /// Views the underlying data as a subslice of the original data.249    ///250    /// To avoid creating `&mut` references that alias, this is forced251    /// to consume the iterator.252    ///253    /// # Examples254    ///255    /// Basic usage:256    ///257    /// ```258    /// // First, we need a slice to call the `iter_mut` method on:259    /// let mut slice = &mut [1, 2, 3];260    ///261    /// // Then we call `iter_mut` on the slice to get the `IterMut` struct:262    /// let mut iter = slice.iter_mut();263    /// // Now, we call the `next` method to remove the first element of the iterator,264    /// // unwrap and dereference what we get from `next` and increase its value by 1:265    /// *iter.next().unwrap() += 1;266    /// // Here the iterator does not contain the first element of the slice any more,267    /// // so `into_slice` only returns the last two elements of the slice,268    /// // and so this prints "[2, 3]":269    /// println!("{:?}", iter.into_slice());270    /// // The underlying slice still contains three elements, but its first element271    /// // was increased by 1, so this prints "[2, 2, 3]":272    /// println!("{:?}", slice);273    /// ```274    #[must_use = "`self` will be dropped if the result is not used"]275    #[stable(feature = "iter_to_slice", since = "1.4.0")]276    pub fn into_slice(self) -> &'a mut [T] {277        // SAFETY: the iterator was created from a mutable slice with pointer278        // `self.ptr` and length `len!(self)`. This guarantees that all the prerequisites279        // for `from_raw_parts_mut` are fulfilled.280        unsafe { from_raw_parts_mut(self.ptr.as_ptr(), len!(self)) }281    }282283    /// Views the underlying data as a subslice of the original data.284    ///285    /// # Examples286    ///287    /// Basic usage:288    ///289    /// ```290    /// // First, we need a slice to call the `iter_mut` method on:291    /// let slice = &mut [1, 2, 3];292    ///293    /// // Then we call `iter_mut` on the slice to get the `IterMut` iterator:294    /// let mut iter = slice.iter_mut();295    /// // Here `as_slice` still returns the whole slice, so this prints "[1, 2, 3]":296    /// println!("{:?}", iter.as_slice());297    ///298    /// // Now, we call the `next` method to remove the first element from the iterator299    /// // and increment its value:300    /// *iter.next().unwrap() += 1;301    /// // Here the iterator does not contain the first element of the slice any more,302    /// // so `as_slice` only returns the last two elements of the slice,303    /// // and so this prints "[2, 3]":304    /// println!("{:?}", iter.as_slice());305    ///306    /// // The underlying slice still contains three elements, but its first element307    /// // was increased by 1, so this prints "[2, 2, 3]":308    /// println!("{:?}", slice);309    /// ```310    #[must_use]311    #[stable(feature = "slice_iter_mut_as_slice", since = "1.53.0")]312    #[inline]313    pub fn as_slice(&self) -> &[T] {314        self.make_slice()315    }316317    /// Views the underlying data as a mutable subslice of the original data.318    ///319    /// # Examples320    ///321    /// Basic usage:322    ///323    /// ```324    /// #![feature(slice_iter_mut_as_mut_slice)]325    ///326    /// let mut slice: &mut [usize] = &mut [1, 2, 3];327    ///328    /// // First, we get the iterator:329    /// let mut iter = slice.iter_mut();330    /// // Then, we get a mutable slice from it:331    /// let mut_slice = iter.as_mut_slice();332    /// // So if we check what the `as_mut_slice` method returned, we have "[1, 2, 3]":333    /// assert_eq!(mut_slice, &mut [1, 2, 3]);334    ///335    /// // We can use it to mutate the slice:336    /// mut_slice[0] = 4;337    /// mut_slice[2] = 5;338    ///339    /// // Next, we can move to the second element of the slice, checking that340    /// // it yields the value we just wrote:341    /// assert_eq!(iter.next(), Some(&mut 4));342    /// // Now `as_mut_slice` returns "[2, 5]":343    /// assert_eq!(iter.as_mut_slice(), &mut [2, 5]);344    /// ```345    #[must_use]346    // FIXME: Uncomment the `AsMut<[T]>` impl when this gets stabilized.347    #[unstable(feature = "slice_iter_mut_as_mut_slice", issue = "93079")]348    pub fn as_mut_slice(&mut self) -> &mut [T] {349        // SAFETY: the iterator was created from a mutable slice with pointer350        // `self.ptr` and length `len!(self)`. This guarantees that all the prerequisites351        // for `from_raw_parts_mut` are fulfilled.352        unsafe { from_raw_parts_mut(self.ptr.as_ptr(), len!(self)) }353    }354}355356#[stable(feature = "slice_iter_mut_as_slice", since = "1.53.0")]357impl<T> AsRef<[T]> for IterMut<'_, T> {358    #[inline]359    fn as_ref(&self) -> &[T] {360        self.as_slice()361    }362}363364// #[stable(feature = "slice_iter_mut_as_mut_slice", since = "FIXME")]365// impl<T> AsMut<[T]> for IterMut<'_, T> {366//     fn as_mut(&mut self) -> &mut [T] {367//         self.as_mut_slice()368//     }369// }370371iterator! {struct IterMut -> *mut T, &'a mut T, mut, {mut}, as_mut, each_mut, {}}372373/// An internal abstraction over the splitting iterators, so that374/// splitn, splitn_mut etc can be implemented once.375#[doc(hidden)]376pub(super) trait SplitIter: DoubleEndedIterator {377    /// Marks the underlying iterator as complete, extracting the remaining378    /// portion of the slice.379    fn finish(&mut self) -> Option<Self::Item>;380}381382/// An iterator over subslices separated by elements that match a predicate383/// function.384///385/// This struct is created by the [`split`] method on [slices].386///387/// # Example388///389/// ```390/// let slice = [10, 40, 33, 20];391/// let mut iter = slice.split(|num| num % 3 == 0);392/// assert_eq!(iter.next(), Some(&[10, 40][..]));393/// assert_eq!(iter.next(), Some(&[20][..]));394/// assert_eq!(iter.next(), None);395/// ```396///397/// [`split`]: slice::split398/// [slices]: slice399#[stable(feature = "rust1", since = "1.0.0")]400#[must_use = "iterators are lazy and do nothing unless consumed"]401pub struct Split<'a, T: 'a, P>402where403    P: FnMut(&T) -> bool,404{405    // Used for `SplitWhitespace` and `SplitAsciiWhitespace` `as_str` methods406    pub(crate) v: &'a [T],407    pred: P,408    // Used for `SplitAsciiWhitespace` `as_str` method409    pub(crate) finished: bool,410}411412impl<'a, T: 'a, P: FnMut(&T) -> bool> Split<'a, T, P> {413    #[inline]414    pub(super) fn new(slice: &'a [T], pred: P) -> Self {415        Self { v: slice, pred, finished: false }416    }417    /// Returns a slice which contains items not yet handled by split.418    /// # Example419    ///420    /// ```421    /// #![feature(split_as_slice)]422    /// let slice = [1,2,3,4,5];423    /// let mut split = slice.split(|v| v % 2 == 0);424    /// assert!(split.next().is_some());425    /// assert_eq!(split.as_slice(), &[3,4,5]);426    /// ```427    #[unstable(feature = "split_as_slice", issue = "96137")]428    pub fn as_slice(&self) -> &'a [T] {429        if self.finished { &[] } else { &self.v }430    }431}432433#[stable(feature = "core_impl_debug", since = "1.9.0")]434impl<T: fmt::Debug, P> fmt::Debug for Split<'_, T, P>435where436    P: FnMut(&T) -> bool,437{438    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {439        f.debug_struct("Split").field("v", &self.v).field("finished", &self.finished).finish()440    }441}442443// FIXME(#26925) Remove in favor of `#[derive(Clone)]`444#[stable(feature = "rust1", since = "1.0.0")]445impl<T, P> Clone for Split<'_, T, P>446where447    P: Clone + FnMut(&T) -> bool,448{449    fn clone(&self) -> Self {450        Split { v: self.v, pred: self.pred.clone(), finished: self.finished }451    }452}453454#[stable(feature = "rust1", since = "1.0.0")]455impl<'a, T, P> Iterator for Split<'a, T, P>456where457    P: FnMut(&T) -> bool,458{459    type Item = &'a [T];460461    #[inline]462    fn next(&mut self) -> Option<&'a [T]> {463        if self.finished {464            return None;465        }466467        match self.v.iter().position(|x| (self.pred)(x)) {468            None => self.finish(),469            Some(idx) => {470                let (left, right) =471                    // SAFETY: if v.iter().position returns Some(idx), that472                    // idx is definitely a valid index for v473                    unsafe { (self.v.get_unchecked(..idx), self.v.get_unchecked(idx + 1..)) };474                let ret = Some(left);475                self.v = right;476                ret477            }478        }479    }480481    #[inline]482    fn size_hint(&self) -> (usize, Option<usize>) {483        if self.finished {484            (0, Some(0))485        } else {486            // If the predicate doesn't match anything, we yield one slice.487            // If it matches every element, we yield `len() + 1` empty slices.488            (1, Some(self.v.len() + 1))489        }490    }491}492493#[stable(feature = "rust1", since = "1.0.0")]494impl<'a, T, P> DoubleEndedIterator for Split<'a, T, P>495where496    P: FnMut(&T) -> bool,497{498    #[inline]499    fn next_back(&mut self) -> Option<&'a [T]> {500        if self.finished {501            return None;502        }503504        match self.v.iter().rposition(|x| (self.pred)(x)) {505            None => self.finish(),506            Some(idx) => {507                let (left, right) =508                    // SAFETY: if v.iter().rposition returns Some(idx), then509                    // idx is definitely a valid index for v510                    unsafe { (self.v.get_unchecked(..idx), self.v.get_unchecked(idx + 1..)) };511                let ret = Some(right);512                self.v = left;513                ret514            }515        }516    }517}518519impl<'a, T, P> SplitIter for Split<'a, T, P>520where521    P: FnMut(&T) -> bool,522{523    #[inline]524    fn finish(&mut self) -> Option<&'a [T]> {525        if self.finished {526            None527        } else {528            self.finished = true;529            Some(self.v)530        }531    }532}533534#[stable(feature = "fused", since = "1.26.0")]535impl<T, P> FusedIterator for Split<'_, T, P> where P: FnMut(&T) -> bool {}536537/// An iterator over subslices separated by elements that match a predicate538/// function. Unlike `Split`, it contains the matched part as a terminator539/// of the subslice.540///541/// This struct is created by the [`split_inclusive`] method on [slices].542///543/// # Example544///545/// ```546/// let slice = [10, 40, 33, 20];547/// let mut iter = slice.split_inclusive(|num| num % 3 == 0);548/// assert_eq!(iter.next(), Some(&[10, 40, 33][..]));549/// assert_eq!(iter.next(), Some(&[20][..]));550/// assert_eq!(iter.next(), None);551/// ```552///553/// [`split_inclusive`]: slice::split_inclusive554/// [slices]: slice555#[stable(feature = "split_inclusive", since = "1.51.0")]556#[must_use = "iterators are lazy and do nothing unless consumed"]557pub struct SplitInclusive<'a, T: 'a, P>558where559    P: FnMut(&T) -> bool,560{561    v: &'a [T],562    pred: P,563    finished: bool,564}565566impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitInclusive<'a, T, P> {567    #[inline]568    pub(super) fn new(slice: &'a [T], pred: P) -> Self {569        let finished = slice.is_empty();570        Self { v: slice, pred, finished }571    }572}573574#[stable(feature = "split_inclusive", since = "1.51.0")]575impl<T: fmt::Debug, P> fmt::Debug for SplitInclusive<'_, T, P>576where577    P: FnMut(&T) -> bool,578{579    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {580        f.debug_struct("SplitInclusive")581            .field("v", &self.v)582            .field("finished", &self.finished)583            .finish()584    }585}586587// FIXME(#26925) Remove in favor of `#[derive(Clone)]`588#[stable(feature = "split_inclusive", since = "1.51.0")]589impl<T, P> Clone for SplitInclusive<'_, T, P>590where591    P: Clone + FnMut(&T) -> bool,592{593    fn clone(&self) -> Self {594        SplitInclusive { v: self.v, pred: self.pred.clone(), finished: self.finished }595    }596}597598#[stable(feature = "split_inclusive", since = "1.51.0")]599impl<'a, T, P> Iterator for SplitInclusive<'a, T, P>600where601    P: FnMut(&T) -> bool,602{603    type Item = &'a [T];604605    #[inline]606    fn next(&mut self) -> Option<&'a [T]> {607        if self.finished {608            return None;609        }610611        let idx =612            self.v.iter().position(|x| (self.pred)(x)).map(|idx| idx + 1).unwrap_or(self.v.len());613        if idx == self.v.len() {614            self.finished = true;615        }616        let ret = Some(&self.v[..idx]);617        self.v = &self.v[idx..];618        ret619    }620621    #[inline]622    fn size_hint(&self) -> (usize, Option<usize>) {623        if self.finished {624            (0, Some(0))625        } else {626            // If the predicate doesn't match anything, we yield one slice.627            // If it matches every element, we yield `len()` one-element slices,628            // or a single empty slice.629            (1, Some(cmp::max(1, self.v.len())))630        }631    }632}633634#[stable(feature = "split_inclusive", since = "1.51.0")]635impl<'a, T, P> DoubleEndedIterator for SplitInclusive<'a, T, P>636where637    P: FnMut(&T) -> bool,638{639    #[inline]640    fn next_back(&mut self) -> Option<&'a [T]> {641        if self.finished {642            return None;643        }644645        // The last index of self.v is already checked and found to match646        // by the last iteration, so we start searching a new match647        // one index to the left.648        let remainder = if self.v.is_empty() { &[] } else { &self.v[..(self.v.len() - 1)] };649        let idx = remainder.iter().rposition(|x| (self.pred)(x)).map(|idx| idx + 1).unwrap_or(0);650        if idx == 0 {651            self.finished = true;652        }653        let ret = Some(&self.v[idx..]);654        self.v = &self.v[..idx];655        ret656    }657}658659#[stable(feature = "split_inclusive", since = "1.51.0")]660impl<T, P> FusedIterator for SplitInclusive<'_, T, P> where P: FnMut(&T) -> bool {}661662/// An iterator over the mutable subslices of the vector which are separated663/// by elements that match `pred`.664///665/// This struct is created by the [`split_mut`] method on [slices].666///667/// # Example668///669/// ```670/// let mut v = [10, 40, 30, 20, 60, 50];671/// let iter = v.split_mut(|num| *num % 3 == 0);672/// ```673///674/// [`split_mut`]: slice::split_mut675/// [slices]: slice676#[stable(feature = "rust1", since = "1.0.0")]677#[must_use = "iterators are lazy and do nothing unless consumed"]678pub struct SplitMut<'a, T: 'a, P>679where680    P: FnMut(&T) -> bool,681{682    v: &'a mut [T],683    pred: P,684    finished: bool,685}686687impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitMut<'a, T, P> {688    #[inline]689    pub(super) fn new(slice: &'a mut [T], pred: P) -> Self {690        Self { v: slice, pred, finished: false }691    }692}693694#[stable(feature = "core_impl_debug", since = "1.9.0")]695impl<T: fmt::Debug, P> fmt::Debug for SplitMut<'_, T, P>696where697    P: FnMut(&T) -> bool,698{699    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {700        f.debug_struct("SplitMut").field("v", &self.v).field("finished", &self.finished).finish()701    }702}703704impl<'a, T, P> SplitIter for SplitMut<'a, T, P>705where706    P: FnMut(&T) -> bool,707{708    #[inline]709    fn finish(&mut self) -> Option<&'a mut [T]> {710        if self.finished {711            None712        } else {713            self.finished = true;714            Some(mem::take(&mut self.v))715        }716    }717}718719#[stable(feature = "rust1", since = "1.0.0")]720impl<'a, T, P> Iterator for SplitMut<'a, T, P>721where722    P: FnMut(&T) -> bool,723{724    type Item = &'a mut [T];725726    #[inline]727    fn next(&mut self) -> Option<&'a mut [T]> {728        if self.finished {729            return None;730        }731732        match self.v.iter().position(|x| (self.pred)(x)) {733            None => self.finish(),734            Some(idx) => {735                let tmp = mem::take(&mut self.v);736                // idx is the index of the element we are splitting on. We want to set self to the737                // region after idx, and return the subslice before and not including idx.738                // So first we split after idx739                let (head, tail) = tmp.split_at_mut(idx + 1);740                self.v = tail;741                // Then return the subslice up to but not including the found element742                Some(&mut head[..idx])743            }744        }745    }746747    #[inline]748    fn size_hint(&self) -> (usize, Option<usize>) {749        if self.finished {750            (0, Some(0))751        } else {752            // If the predicate doesn't match anything, we yield one slice.753            // If it matches every element, we yield `len() + 1` empty slices.754            (1, Some(self.v.len() + 1))755        }756    }757}758759#[stable(feature = "rust1", since = "1.0.0")]760impl<'a, T, P> DoubleEndedIterator for SplitMut<'a, T, P>761where762    P: FnMut(&T) -> bool,763{764    #[inline]765    fn next_back(&mut self) -> Option<&'a mut [T]> {766        if self.finished {767            return None;768        }769770        let idx_opt = {771            // work around borrowck limitations772            let pred = &mut self.pred;773            self.v.iter().rposition(|x| (*pred)(x))774        };775        match idx_opt {776            None => self.finish(),777            Some(idx) => {778                let tmp = mem::take(&mut self.v);779                let (head, tail) = tmp.split_at_mut(idx);780                self.v = head;781                Some(&mut tail[1..])782            }783        }784    }785}786787#[stable(feature = "fused", since = "1.26.0")]788impl<T, P> FusedIterator for SplitMut<'_, T, P> where P: FnMut(&T) -> bool {}789790/// An iterator over the mutable subslices of the vector which are separated791/// by elements that match `pred`. Unlike `SplitMut`, it contains the matched792/// parts in the ends of the subslices.793///794/// This struct is created by the [`split_inclusive_mut`] method on [slices].795///796/// # Example797///798/// ```799/// let mut v = [10, 40, 30, 20, 60, 50];800/// let iter = v.split_inclusive_mut(|num| *num % 3 == 0);801/// ```802///803/// [`split_inclusive_mut`]: slice::split_inclusive_mut804/// [slices]: slice805#[stable(feature = "split_inclusive", since = "1.51.0")]806#[must_use = "iterators are lazy and do nothing unless consumed"]807pub struct SplitInclusiveMut<'a, T: 'a, P>808where809    P: FnMut(&T) -> bool,810{811    v: &'a mut [T],812    pred: P,813    finished: bool,814}815816impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitInclusiveMut<'a, T, P> {817    #[inline]818    pub(super) fn new(slice: &'a mut [T], pred: P) -> Self {819        let finished = slice.is_empty();820        Self { v: slice, pred, finished }821    }822}823824#[stable(feature = "split_inclusive", since = "1.51.0")]825impl<T: fmt::Debug, P> fmt::Debug for SplitInclusiveMut<'_, T, P>826where827    P: FnMut(&T) -> bool,828{829    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {830        f.debug_struct("SplitInclusiveMut")831            .field("v", &self.v)832            .field("finished", &self.finished)833            .finish()834    }835}836837#[stable(feature = "split_inclusive", since = "1.51.0")]838impl<'a, T, P> Iterator for SplitInclusiveMut<'a, T, P>839where840    P: FnMut(&T) -> bool,841{842    type Item = &'a mut [T];843844    #[inline]845    fn next(&mut self) -> Option<&'a mut [T]> {846        if self.finished {847            return None;848        }849850        let idx_opt = {851            // work around borrowck limitations852            let pred = &mut self.pred;853            self.v.iter().position(|x| (*pred)(x))854        };855        let idx = idx_opt.map(|idx| idx + 1).unwrap_or(self.v.len());856        if idx == self.v.len() {857            self.finished = true;858        }859        let tmp = mem::take(&mut self.v);860        let (head, tail) = tmp.split_at_mut(idx);861        self.v = tail;862        Some(head)863    }864865    #[inline]866    fn size_hint(&self) -> (usize, Option<usize>) {867        if self.finished {868            (0, Some(0))869        } else {870            // If the predicate doesn't match anything, we yield one slice.871            // If it matches every element, we yield `len()` one-element slices,872            // or a single empty slice.873            (1, Some(cmp::max(1, self.v.len())))874        }875    }876}877878#[stable(feature = "split_inclusive", since = "1.51.0")]879impl<'a, T, P> DoubleEndedIterator for SplitInclusiveMut<'a, T, P>880where881    P: FnMut(&T) -> bool,882{883    #[inline]884    fn next_back(&mut self) -> Option<&'a mut [T]> {885        if self.finished {886            return None;887        }888889        let idx_opt = if self.v.is_empty() {890            None891        } else {892            // work around borrowck limitations893            let pred = &mut self.pred;894895            // The last index of self.v is already checked and found to match896            // by the last iteration, so we start searching a new match897            // one index to the left.898            let remainder = &self.v[..(self.v.len() - 1)];899            remainder.iter().rposition(|x| (*pred)(x))900        };901        let idx = idx_opt.map(|idx| idx + 1).unwrap_or(0);902        if idx == 0 {903            self.finished = true;904        }905        let tmp = mem::take(&mut self.v);906        let (head, tail) = tmp.split_at_mut(idx);907        self.v = head;908        Some(tail)909    }910}911912#[stable(feature = "split_inclusive", since = "1.51.0")]913impl<T, P> FusedIterator for SplitInclusiveMut<'_, T, P> where P: FnMut(&T) -> bool {}914915/// An iterator over subslices separated by elements that match a predicate916/// function, starting from the end of the slice.917///918/// This struct is created by the [`rsplit`] method on [slices].919///920/// # Example921///922/// ```923/// let slice = [11, 22, 33, 0, 44, 55];924/// let mut iter = slice.rsplit(|num| *num == 0);925/// assert_eq!(iter.next(), Some(&[44, 55][..]));926/// assert_eq!(iter.next(), Some(&[11, 22, 33][..]));927/// assert_eq!(iter.next(), None);928/// ```929///930/// [`rsplit`]: slice::rsplit931/// [slices]: slice932#[stable(feature = "slice_rsplit", since = "1.27.0")]933#[must_use = "iterators are lazy and do nothing unless consumed"]934pub struct RSplit<'a, T: 'a, P>935where936    P: FnMut(&T) -> bool,937{938    inner: Split<'a, T, P>,939}940941impl<'a, T: 'a, P: FnMut(&T) -> bool> RSplit<'a, T, P> {942    #[inline]943    pub(super) fn new(slice: &'a [T], pred: P) -> Self {944        Self { inner: Split::new(slice, pred) }945    }946}947948#[stable(feature = "slice_rsplit", since = "1.27.0")]949impl<T: fmt::Debug, P> fmt::Debug for RSplit<'_, T, P>950where951    P: FnMut(&T) -> bool,952{953    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {954        f.debug_struct("RSplit")955            .field("v", &self.inner.v)956            .field("finished", &self.inner.finished)957            .finish()958    }959}960961// FIXME(#26925) Remove in favor of `#[derive(Clone)]`962#[stable(feature = "slice_rsplit", since = "1.27.0")]963impl<T, P> Clone for RSplit<'_, T, P>964where965    P: Clone + FnMut(&T) -> bool,966{967    fn clone(&self) -> Self {968        RSplit { inner: self.inner.clone() }969    }970}971972#[stable(feature = "slice_rsplit", since = "1.27.0")]973impl<'a, T, P> Iterator for RSplit<'a, T, P>974where975    P: FnMut(&T) -> bool,976{977    type Item = &'a [T];978979    #[inline]980    fn next(&mut self) -> Option<&'a [T]> {981        self.inner.next_back()982    }983984    #[inline]985    fn size_hint(&self) -> (usize, Option<usize>) {986        self.inner.size_hint()987    }988}989990#[stable(feature = "slice_rsplit", since = "1.27.0")]991impl<'a, T, P> DoubleEndedIterator for RSplit<'a, T, P>992where993    P: FnMut(&T) -> bool,994{995    #[inline]996    fn next_back(&mut self) -> Option<&'a [T]> {997        self.inner.next()998    }999}10001001#[stable(feature = "slice_rsplit", since = "1.27.0")]1002impl<'a, T, P> SplitIter for RSplit<'a, T, P>1003where1004    P: FnMut(&T) -> bool,1005{1006    #[inline]1007    fn finish(&mut self) -> Option<&'a [T]> {1008        self.inner.finish()1009    }1010}10111012#[stable(feature = "slice_rsplit", since = "1.27.0")]1013impl<T, P> FusedIterator for RSplit<'_, T, P> where P: FnMut(&T) -> bool {}10141015/// An iterator over the subslices of the vector which are separated1016/// by elements that match `pred`, starting from the end of the slice.1017///1018/// This struct is created by the [`rsplit_mut`] method on [slices].1019///1020/// # Example1021///1022/// ```1023/// let mut slice = [11, 22, 33, 0, 44, 55];1024/// let iter = slice.rsplit_mut(|num| *num == 0);1025/// ```1026///1027/// [`rsplit_mut`]: slice::rsplit_mut1028/// [slices]: slice1029#[stable(feature = "slice_rsplit", since = "1.27.0")]1030#[must_use = "iterators are lazy and do nothing unless consumed"]1031pub struct RSplitMut<'a, T: 'a, P>1032where1033    P: FnMut(&T) -> bool,1034{1035    inner: SplitMut<'a, T, P>,1036}10371038impl<'a, T: 'a, P: FnMut(&T) -> bool> RSplitMut<'a, T, P> {1039    #[inline]1040    pub(super) fn new(slice: &'a mut [T], pred: P) -> Self {1041        Self { inner: SplitMut::new(slice, pred) }1042    }1043}10441045#[stable(feature = "slice_rsplit", since = "1.27.0")]1046impl<T: fmt::Debug, P> fmt::Debug for RSplitMut<'_, T, P>1047where1048    P: FnMut(&T) -> bool,1049{1050    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {1051        f.debug_struct("RSplitMut")1052            .field("v", &self.inner.v)1053            .field("finished", &self.inner.finished)1054            .finish()1055    }1056}10571058#[stable(feature = "slice_rsplit", since = "1.27.0")]1059impl<'a, T, P> SplitIter for RSplitMut<'a, T, P>1060where1061    P: FnMut(&T) -> bool,1062{1063    #[inline]1064    fn finish(&mut self) -> Option<&'a mut [T]> {1065        self.inner.finish()1066    }1067}10681069#[stable(feature = "slice_rsplit", since = "1.27.0")]1070impl<'a, T, P> Iterator for RSplitMut<'a, T, P>1071where1072    P: FnMut(&T) -> bool,1073{1074    type Item = &'a mut [T];10751076    #[inline]1077    fn next(&mut self) -> Option<&'a mut [T]> {1078        self.inner.next_back()1079    }10801081    #[inline]1082    fn size_hint(&self) -> (usize, Option<usize>) {1083        self.inner.size_hint()1084    }1085}10861087#[stable(feature = "slice_rsplit", since = "1.27.0")]1088impl<'a, T, P> DoubleEndedIterator for RSplitMut<'a, T, P>1089where1090    P: FnMut(&T) -> bool,1091{1092    #[inline]1093    fn next_back(&mut self) -> Option<&'a mut [T]> {1094        self.inner.next()1095    }1096}10971098#[stable(feature = "slice_rsplit", since = "1.27.0")]1099impl<T, P> FusedIterator for RSplitMut<'_, T, P> where P: FnMut(&T) -> bool {}11001101/// An private iterator over subslices separated by elements that1102/// match a predicate function, splitting at most a fixed number of1103/// times.1104#[derive(Debug)]1105struct GenericSplitN<I> {1106    iter: I,1107    count: usize,1108}11091110impl<T, I: SplitIter<Item = T>> Iterator for GenericSplitN<I> {1111    type Item = T;11121113    #[inline]1114    fn next(&mut self) -> Option<T> {1115        match self.count {1116            0 => None,1117            1 => {1118                self.count -= 1;1119                self.iter.finish()1120            }1121            _ => {1122                self.count -= 1;1123                self.iter.next()1124            }1125        }1126    }11271128    #[inline]1129    fn size_hint(&self) -> (usize, Option<usize>) {1130        let (lower, upper_opt) = self.iter.size_hint();1131        (1132            cmp::min(self.count, lower),1133            Some(upper_opt.map_or(self.count, |upper| cmp::min(self.count, upper))),1134        )1135    }1136}11371138/// An iterator over subslices separated by elements that match a predicate1139/// function, limited to a given number of splits.1140///1141/// This struct is created by the [`splitn`] method on [slices].1142///1143/// # Example1144///1145/// ```1146/// let slice = [10, 40, 30, 20, 60, 50];1147/// let mut iter = slice.splitn(2, |num| *num % 3 == 0);1148/// assert_eq!(iter.next(), Some(&[10, 40][..]));1149/// assert_eq!(iter.next(), Some(&[20, 60, 50][..]));1150/// assert_eq!(iter.next(), None);1151/// ```1152///1153/// [`splitn`]: slice::splitn1154/// [slices]: slice1155#[stable(feature = "rust1", since = "1.0.0")]1156#[must_use = "iterators are lazy and do nothing unless consumed"]1157pub struct SplitN<'a, T: 'a, P>1158where1159    P: FnMut(&T) -> bool,1160{1161    inner: GenericSplitN<Split<'a, T, P>>,1162}11631164impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitN<'a, T, P> {1165    #[inline]1166    pub(super) fn new(s: Split<'a, T, P>, n: usize) -> Self {1167        Self { inner: GenericSplitN { iter: s, count: n } }1168    }1169}11701171#[stable(feature = "core_impl_debug", since = "1.9.0")]1172impl<T: fmt::Debug, P> fmt::Debug for SplitN<'_, T, P>1173where1174    P: FnMut(&T) -> bool,1175{1176    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {1177        f.debug_struct("SplitN").field("inner", &self.inner).finish()1178    }1179}11801181/// An iterator over subslices separated by elements that match a1182/// predicate function, limited to a given number of splits, starting1183/// from the end of the slice.1184///1185/// This struct is created by the [`rsplitn`] method on [slices].1186///1187/// # Example1188///1189/// ```1190/// let slice = [10, 40, 30, 20, 60, 50];1191/// let mut iter = slice.rsplitn(2, |num| *num % 3 == 0);1192/// assert_eq!(iter.next(), Some(&[50][..]));1193/// assert_eq!(iter.next(), Some(&[10, 40, 30, 20][..]));1194/// assert_eq!(iter.next(), None);1195/// ```1196///1197/// [`rsplitn`]: slice::rsplitn1198/// [slices]: slice1199#[stable(feature = "rust1", since = "1.0.0")]1200#[must_use = "iterators are lazy and do nothing unless consumed"]1201pub struct RSplitN<'a, T: 'a, P>1202where1203    P: FnMut(&T) -> bool,1204{1205    inner: GenericSplitN<RSplit<'a, T, P>>,1206}12071208impl<'a, T: 'a, P: FnMut(&T) -> bool> RSplitN<'a, T, P> {1209    #[inline]1210    pub(super) fn new(s: RSplit<'a, T, P>, n: usize) -> Self {1211        Self { inner: GenericSplitN { iter: s, count: n } }1212    }1213}12141215#[stable(feature = "core_impl_debug", since = "1.9.0")]1216impl<T: fmt::Debug, P> fmt::Debug for RSplitN<'_, T, P>1217where1218    P: FnMut(&T) -> bool,1219{1220    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {1221        f.debug_struct("RSplitN").field("inner", &self.inner).finish()1222    }1223}12241225/// An iterator over subslices separated by elements that match a predicate1226/// function, limited to a given number of splits.1227///1228/// This struct is created by the [`splitn_mut`] method on [slices].1229///1230/// # Example1231///1232/// ```1233/// let mut slice = [10, 40, 30, 20, 60, 50];1234/// let iter = slice.splitn_mut(2, |num| *num % 3 == 0);1235/// ```1236///1237/// [`splitn_mut`]: slice::splitn_mut1238/// [slices]: slice1239#[stable(feature = "rust1", since = "1.0.0")]1240#[must_use = "iterators are lazy and do nothing unless consumed"]1241pub struct SplitNMut<'a, T: 'a, P>1242where1243    P: FnMut(&T) -> bool,1244{1245    inner: GenericSplitN<SplitMut<'a, T, P>>,1246}12471248impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitNMut<'a, T, P> {1249    #[inline]1250    pub(super) fn new(s: SplitMut<'a, T, P>, n: usize) -> Self {1251        Self { inner: GenericSplitN { iter: s, count: n } }1252    }1253}12541255#[stable(feature = "core_impl_debug", since = "1.9.0")]1256impl<T: fmt::Debug, P> fmt::Debug for SplitNMut<'_, T, P>1257where1258    P: FnMut(&T) -> bool,1259{1260    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {1261        f.debug_struct("SplitNMut").field("inner", &self.inner).finish()1262    }1263}12641265/// An iterator over subslices separated by elements that match a1266/// predicate function, limited to a given number of splits, starting1267/// from the end of the slice.1268///1269/// This struct is created by the [`rsplitn_mut`] method on [slices].1270///1271/// # Example1272///1273/// ```1274/// let mut slice = [10, 40, 30, 20, 60, 50];1275/// let iter = slice.rsplitn_mut(2, |num| *num % 3 == 0);1276/// ```1277///1278/// [`rsplitn_mut`]: slice::rsplitn_mut1279/// [slices]: slice1280#[stable(feature = "rust1", since = "1.0.0")]1281#[must_use = "iterators are lazy and do nothing unless consumed"]1282pub struct RSplitNMut<'a, T: 'a, P>1283where1284    P: FnMut(&T) -> bool,1285{1286    inner: GenericSplitN<RSplitMut<'a, T, P>>,1287}12881289impl<'a, T: 'a, P: FnMut(&T) -> bool> RSplitNMut<'a, T, P> {1290    #[inline]1291    pub(super) fn new(s: RSplitMut<'a, T, P>, n: usize) -> Self {1292        Self { inner: GenericSplitN { iter: s, count: n } }1293    }1294}12951296#[stable(feature = "core_impl_debug", since = "1.9.0")]1297impl<T: fmt::Debug, P> fmt::Debug for RSplitNMut<'_, T, P>1298where1299    P: FnMut(&T) -> bool,1300{1301    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {1302        f.debug_struct("RSplitNMut").field("inner", &self.inner).finish()1303    }1304}13051306forward_iterator! { SplitN: T, &'a [T] }1307forward_iterator! { RSplitN: T, &'a [T] }1308forward_iterator! { SplitNMut: T, &'a mut [T] }1309forward_iterator! { RSplitNMut: T, &'a mut [T] }13101311/// An iterator over overlapping subslices of length `size`.1312///1313/// This struct is created by the [`windows`] method on [slices].1314///1315/// # Example1316///1317/// ```1318/// let slice = ['r', 'u', 's', 't'];1319/// let mut iter = slice.windows(2);1320/// assert_eq!(iter.next(), Some(&['r', 'u'][..]));1321/// assert_eq!(iter.next(), Some(&['u', 's'][..]));1322/// assert_eq!(iter.next(), Some(&['s', 't'][..]));1323/// assert_eq!(iter.next(), None);1324/// ```1325///1326/// [`windows`]: slice::windows1327/// [slices]: slice1328#[derive(Debug)]1329#[stable(feature = "rust1", since = "1.0.0")]1330#[must_use = "iterators are lazy and do nothing unless consumed"]1331pub struct Windows<'a, T: 'a> {1332    v: &'a [T],1333    size: NonZero<usize>,1334}13351336impl<'a, T: 'a> Windows<'a, T> {1337    #[inline]1338    pub(super) const fn new(slice: &'a [T], size: NonZero<usize>) -> Self {1339        Self { v: slice, size }1340    }1341}13421343// FIXME(#26925) Remove in favor of `#[derive(Clone)]`1344#[stable(feature = "rust1", since = "1.0.0")]1345impl<T> Clone for Windows<'_, T> {1346    fn clone(&self) -> Self {1347        Windows { v: self.v, size: self.size }1348    }1349}13501351#[stable(feature = "rust1", since = "1.0.0")]1352impl<'a, T> Iterator for Windows<'a, T> {1353    type Item = &'a [T];13541355    #[inline]1356    fn next(&mut self) -> Option<&'a [T]> {1357        if self.size.get() > self.v.len() {1358            None1359        } else {1360            let ret = Some(&self.v[..self.size.get()]);1361            self.v = &self.v[1..];1362            ret1363        }1364    }13651366    #[inline]1367    fn size_hint(&self) -> (usize, Option<usize>) {1368        if self.size.get() > self.v.len() {1369            (0, Some(0))1370        } else {1371            let size = self.v.len() - self.size.get() + 1;1372            (size, Some(size))1373        }1374    }13751376    #[inline]1377    fn count(self) -> usize {1378        self.len()1379    }13801381    #[inline]1382    fn nth(&mut self, n: usize) -> Option<Self::Item> {1383        let size = self.size.get();1384        if let Some(rest) = self.v.get(n..)1385            && let Some(nth) = rest.get(..size)1386        {1387            self.v = &rest[1..];1388            Some(nth)1389        } else {1390            // setting length to 0 is cheaper than overwriting the pointer when assigning &[]1391            self.v = &self.v[..0]; // cheaper than &[]1392            None1393        }1394    }13951396    #[inline]1397    fn last(self) -> Option<Self::Item> {1398        if self.size.get() > self.v.len() {1399            None1400        } else {1401            let start = self.v.len() - self.size.get();1402            Some(&self.v[start..])1403        }1404    }14051406    unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {1407        // SAFETY: since the caller guarantees that `i` is in bounds,1408        // which means that `i` cannot overflow an `isize`, and the1409        // slice created by `from_raw_parts` is a subslice of `self.v`1410        // thus is guaranteed to be valid for the lifetime `'a` of `self.v`.1411        unsafe { from_raw_parts(self.v.as_ptr().add(idx), self.size.get()) }1412    }1413}14141415#[stable(feature = "rust1", since = "1.0.0")]1416impl<'a, T> DoubleEndedIterator for Windows<'a, T> {1417    #[inline]1418    fn next_back(&mut self) -> Option<Self::Item> {1419        self.nth_back(0)1420    }14211422    #[inline]1423    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {1424        if let Some(end) = self.v.len().checked_sub(n)1425            && let Some(start) = end.checked_sub(self.size.get())1426        {1427            let res = &self.v[start..end];1428            self.v = &self.v[..end - 1];1429            Some(res)1430        } else {1431            self.v = &self.v[..0]; // cheaper than &[]1432            None1433        }1434    }1435}14361437#[stable(feature = "rust1", since = "1.0.0")]1438impl<T> ExactSizeIterator for Windows<'_, T> {}14391440#[unstable(feature = "trusted_len", issue = "37572")]1441unsafe impl<T> TrustedLen for Windows<'_, T> {}14421443#[stable(feature = "fused", since = "1.26.0")]1444impl<T> FusedIterator for Windows<'_, T> {}14451446#[doc(hidden)]1447#[unstable(feature = "trusted_random_access", issue = "none")]1448unsafe impl<'a, T> TrustedRandomAccess for Windows<'a, T> {}14491450#[doc(hidden)]1451#[unstable(feature = "trusted_random_access", issue = "none")]1452unsafe impl<'a, T> TrustedRandomAccessNoCoerce for Windows<'a, T> {1453    const MAY_HAVE_SIDE_EFFECT: bool = false;1454}14551456/// An iterator over a slice in (non-overlapping) chunks (`chunk_size` elements at a1457/// time), starting at the beginning of the slice.1458///1459/// When the slice len is not evenly divided by the chunk size, the last slice1460/// of the iteration will be the remainder.1461///1462/// This struct is created by the [`chunks`] method on [slices].1463///1464/// # Example1465///1466/// ```1467/// let slice = ['l', 'o', 'r', 'e', 'm'];1468/// let mut iter = slice.chunks(2);1469/// assert_eq!(iter.next(), Some(&['l', 'o'][..]));1470/// assert_eq!(iter.next(), Some(&['r', 'e'][..]));1471/// assert_eq!(iter.next(), Some(&['m'][..]));1472/// assert_eq!(iter.next(), None);1473/// ```1474///1475/// [`chunks`]: slice::chunks1476/// [slices]: slice1477#[derive(Debug)]1478#[stable(feature = "rust1", since = "1.0.0")]1479#[must_use = "iterators are lazy and do nothing unless consumed"]1480pub struct Chunks<'a, T: 'a> {1481    v: &'a [T],1482    chunk_size: usize,1483}14841485impl<'a, T: 'a> Chunks<'a, T> {1486    #[inline]1487    pub(super) const fn new(slice: &'a [T], size: usize) -> Self {1488        Self { v: slice, chunk_size: size }1489    }1490}14911492// FIXME(#26925) Remove in favor of `#[derive(Clone)]`1493#[stable(feature = "rust1", since = "1.0.0")]1494impl<T> Clone for Chunks<'_, T> {1495    fn clone(&self) -> Self {1496        Chunks { v: self.v, chunk_size: self.chunk_size }1497    }1498}14991500#[stable(feature = "rust1", since = "1.0.0")]1501impl<'a, T> Iterator for Chunks<'a, T> {1502    type Item = &'a [T];15031504    #[inline]1505    fn next(&mut self) -> Option<&'a [T]> {1506        if self.v.is_empty() {1507            None1508        } else {1509            let chunksz = cmp::min(self.v.len(), self.chunk_size);1510            let (fst, snd) = self.v.split_at(chunksz);1511            self.v = snd;1512            Some(fst)1513        }1514    }15151516    #[inline]1517    fn size_hint(&self) -> (usize, Option<usize>) {1518        if self.v.is_empty() {1519            (0, Some(0))1520        } else {1521            let n = self.v.len().div_ceil(self.chunk_size);1522            (n, Some(n))1523        }1524    }15251526    #[inline]1527    fn count(self) -> usize {1528        self.len()1529    }15301531    #[inline]1532    fn nth(&mut self, n: usize) -> Option<Self::Item> {1533        if let Some(start) = n.checked_mul(self.chunk_size)1534            && start < self.v.len()1535        {1536            let rest = &self.v[start..];1537            let (chunk, rest) = rest.split_at(self.chunk_size.min(rest.len()));1538            self.v = rest;1539            Some(chunk)1540        } else {1541            self.v = &self.v[..0]; // cheaper than &[]1542            None1543        }1544    }15451546    #[inline]1547    fn last(self) -> Option<Self::Item> {1548        if self.v.is_empty() {1549            None1550        } else {1551            let start = (self.v.len() - 1) / self.chunk_size * self.chunk_size;1552            Some(&self.v[start..])1553        }1554    }15551556    unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {1557        let start = idx * self.chunk_size;1558        // SAFETY: the caller guarantees that `i` is in bounds,1559        // which means that `start` must be in bounds of the1560        // underlying `self.v` slice, and we made sure that `len`1561        // is also in bounds of `self.v`. Thus, `start` cannot overflow1562        // an `isize`, and the slice constructed by `from_raw_parts`1563        // is a subslice of `self.v` which is guaranteed to be valid1564        // for the lifetime `'a` of `self.v`.1565        unsafe {1566            let len = cmp::min(self.v.len().unchecked_sub(start), self.chunk_size);1567            from_raw_parts(self.v.as_ptr().add(start), len)1568        }1569    }1570}15711572#[stable(feature = "rust1", since = "1.0.0")]1573impl<'a, T> DoubleEndedIterator for Chunks<'a, T> {1574    #[inline]1575    fn next_back(&mut self) -> Option<&'a [T]> {1576        if self.v.is_empty() {1577            None1578        } else {1579            let remainder = self.v.len() % self.chunk_size;1580            let chunksz = if remainder != 0 { remainder } else { self.chunk_size };1581            // SAFETY: split_at_unchecked requires the argument be less than or1582            // equal to the length. This is guaranteed, but subtle: `chunksz`1583            // will always either be `self.v.len() % self.chunk_size`, which1584            // will always evaluate to strictly less than `self.v.len()` (or1585            // panic, in the case that `self.chunk_size` is zero), or it can be1586            // `self.chunk_size`, in the case that the length is exactly1587            // divisible by the chunk size.1588            //1589            // While it seems like using `self.chunk_size` in this case could1590            // lead to a value greater than `self.v.len()`, it cannot: if1591            // `self.chunk_size` were greater than `self.v.len()`, then1592            // `self.v.len() % self.chunk_size` would return nonzero (note that1593            // in this branch of the `if`, we already know that `self.v` is1594            // non-empty).1595            let (fst, snd) = unsafe { self.v.split_at_unchecked(self.v.len() - chunksz) };1596            self.v = fst;1597            Some(snd)1598        }1599    }16001601    #[inline]1602    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {1603        let len = self.len();1604        if n < len {1605            let start = (len - 1 - n) * self.chunk_size;1606            let end = start + (self.v.len() - start).min(self.chunk_size);1607            let nth_back = &self.v[start..end];1608            self.v = &self.v[..start];1609            Some(nth_back)1610        } else {1611            self.v = &self.v[..0]; // cheaper than &[]1612            None1613        }1614    }1615}16161617#[stable(feature = "rust1", since = "1.0.0")]1618impl<T> ExactSizeIterator for Chunks<'_, T> {}16191620#[unstable(feature = "trusted_len", issue = "37572")]1621unsafe impl<T> TrustedLen for Chunks<'_, T> {}16221623#[stable(feature = "fused", since = "1.26.0")]1624impl<T> FusedIterator for Chunks<'_, T> {}16251626#[doc(hidden)]1627#[unstable(feature = "trusted_random_access", issue = "none")]1628unsafe impl<'a, T> TrustedRandomAccess for Chunks<'a, T> {}16291630#[doc(hidden)]1631#[unstable(feature = "trusted_random_access", issue = "none")]1632unsafe impl<'a, T> TrustedRandomAccessNoCoerce for Chunks<'a, T> {1633    const MAY_HAVE_SIDE_EFFECT: bool = false;1634}16351636/// An iterator over a slice in (non-overlapping) mutable chunks (`chunk_size`1637/// elements at a time), starting at the beginning of the slice.1638///1639/// When the slice len is not evenly divided by the chunk size, the last slice1640/// of the iteration will be the remainder.1641///1642/// This struct is created by the [`chunks_mut`] method on [slices].1643///1644/// # Example1645///1646/// ```1647/// let mut slice = ['l', 'o', 'r', 'e', 'm'];1648/// let iter = slice.chunks_mut(2);1649/// ```1650///1651/// [`chunks_mut`]: slice::chunks_mut1652/// [slices]: slice1653#[derive(Debug)]1654#[stable(feature = "rust1", since = "1.0.0")]1655#[must_use = "iterators are lazy and do nothing unless consumed"]1656pub struct ChunksMut<'a, T: 'a> {1657    /// # Safety1658    /// This slice pointer must point at a valid region of `T` with at least length `v.len()`. Normally,1659    /// those requirements would mean that we could instead use a `&mut [T]` here, but we cannot1660    /// because `__iterator_get_unchecked` needs to return `&mut [T]`, which guarantees certain aliasing1661    /// properties that we cannot uphold if we hold on to the full original `&mut [T]`. Wrapping a raw1662    /// slice instead lets us hand out non-overlapping `&mut [T]` subslices of the slice we wrap.1663    v: *mut [T],1664    chunk_size: usize,1665    _marker: PhantomData<&'a mut T>,1666}16671668impl<'a, T: 'a> ChunksMut<'a, T> {1669    #[inline]1670    pub(super) const fn new(slice: &'a mut [T], size: usize) -> Self {1671        Self { v: slice, chunk_size: size, _marker: PhantomData }1672    }1673}16741675#[stable(feature = "rust1", since = "1.0.0")]1676impl<'a, T> Iterator for ChunksMut<'a, T> {1677    type Item = &'a mut [T];16781679    #[inline]1680    fn next(&mut self) -> Option<&'a mut [T]> {1681        if self.v.is_empty() {1682            None1683        } else {1684            let sz = cmp::min(self.v.len(), self.chunk_size);1685            // SAFETY: The self.v contract ensures that any split_at_mut is valid.1686            let (head, tail) = unsafe { self.v.split_at_mut(sz) };1687            self.v = tail;1688            // SAFETY: Nothing else points to or will point to the contents of this slice.1689            Some(unsafe { &mut *head })1690        }1691    }16921693    #[inline]1694    fn size_hint(&self) -> (usize, Option<usize>) {1695        if self.v.is_empty() {1696            (0, Some(0))1697        } else {1698            let n = self.v.len().div_ceil(self.chunk_size);1699            (n, Some(n))1700        }1701    }17021703    #[inline]1704    fn count(self) -> usize {1705        self.len()1706    }17071708    #[inline]1709    fn nth(&mut self, n: usize) -> Option<&'a mut [T]> {1710        if let Some(start) = n.checked_mul(self.chunk_size)1711            && start < self.v.len()1712        {1713            // SAFETY: `start < self.v.len()` ensures this is in bounds1714            let (_, rest) = unsafe { self.v.split_at_mut(start) };1715            // SAFETY: `.min(rest.len()` ensures this is in bounds1716            let (chunk, rest) = unsafe { rest.split_at_mut(self.chunk_size.min(rest.len())) };1717            self.v = rest;1718            // SAFETY: Nothing else points to or will point to the contents of this slice.1719            Some(unsafe { &mut *chunk })1720        } else {1721            self.v = &mut [];1722            None1723        }1724    }17251726    #[inline]1727    fn last(self) -> Option<Self::Item> {1728        if self.v.is_empty() {1729            None1730        } else {1731            let start = (self.v.len() - 1) / self.chunk_size * self.chunk_size;1732            // SAFETY: Nothing else points to or will point to the contents of this slice.1733            Some(unsafe { &mut *self.v.get_unchecked_mut(start..) })1734        }1735    }17361737    unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {1738        let start = idx * self.chunk_size;1739        // SAFETY: see comments for `Chunks::__iterator_get_unchecked` and `self.v`.1740        //1741        // Also note that the caller also guarantees that we're never called1742        // with the same index again, and that no other methods that will1743        // access this subslice are called, so it is valid for the returned1744        // slice to be mutable.1745        unsafe {1746            let len = cmp::min(self.v.len().unchecked_sub(start), self.chunk_size);1747            from_raw_parts_mut(self.v.as_mut_ptr().add(start), len)1748        }1749    }1750}17511752#[stable(feature = "rust1", since = "1.0.0")]1753impl<'a, T> DoubleEndedIterator for ChunksMut<'a, T> {1754    #[inline]1755    fn next_back(&mut self) -> Option<&'a mut [T]> {1756        if self.v.is_empty() {1757            None1758        } else {1759            let remainder = self.v.len() % self.chunk_size;1760            let sz = if remainder != 0 { remainder } else { self.chunk_size };1761            let len = self.v.len();1762            // SAFETY: Similar to `Chunks::next_back`1763            let (head, tail) = unsafe { self.v.split_at_mut_unchecked(len - sz) };1764            self.v = head;1765            // SAFETY: Nothing else points to or will point to the contents of this slice.1766            Some(unsafe { &mut *tail })1767        }1768    }17691770    #[inline]1771    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {1772        let len = self.len();1773        if n < len {1774            let start = (len - 1 - n) * self.chunk_size;1775            let end = match start.checked_add(self.chunk_size) {1776                Some(res) => cmp::min(self.v.len(), res),1777                None => self.v.len(),1778            };1779            // SAFETY: The self.v contract ensures that any split_at_mut is valid.1780            let (temp, _tail) = unsafe { self.v.split_at_mut(end) };1781            // SAFETY: The self.v contract ensures that any split_at_mut is valid.1782            let (head, nth_back) = unsafe { temp.split_at_mut(start) };1783            self.v = head;1784            // SAFETY: Nothing else points to or will point to the contents of this slice.1785            Some(unsafe { &mut *nth_back })1786        } else {1787            self.v = &mut [];1788            None1789        }1790    }1791}17921793#[stable(feature = "rust1", since = "1.0.0")]1794impl<T> ExactSizeIterator for ChunksMut<'_, T> {}17951796#[unstable(feature = "trusted_len", issue = "37572")]1797unsafe impl<T> TrustedLen for ChunksMut<'_, T> {}17981799#[stable(feature = "fused", since = "1.26.0")]1800impl<T> FusedIterator for ChunksMut<'_, T> {}18011802#[doc(hidden)]1803#[unstable(feature = "trusted_random_access", issue = "none")]1804unsafe impl<'a, T> TrustedRandomAccess for ChunksMut<'a, T> {}18051806#[doc(hidden)]1807#[unstable(feature = "trusted_random_access", issue = "none")]1808unsafe impl<'a, T> TrustedRandomAccessNoCoerce for ChunksMut<'a, T> {1809    const MAY_HAVE_SIDE_EFFECT: bool = false;1810}18111812#[stable(feature = "rust1", since = "1.0.0")]1813unsafe impl<T> Send for ChunksMut<'_, T> where T: Send {}18141815#[stable(feature = "rust1", since = "1.0.0")]1816unsafe impl<T> Sync for ChunksMut<'_, T> where T: Sync {}18171818/// An iterator over a slice in (non-overlapping) chunks (`chunk_size` elements at a1819/// time), starting at the beginning of the slice.1820///1821/// When the slice len is not evenly divided by the chunk size, the last1822/// up to `chunk_size-1` elements will be omitted but can be retrieved from1823/// the [`remainder`] function from the iterator.1824///1825/// This struct is created by the [`chunks_exact`] method on [slices].1826///1827/// # Example1828///1829/// ```1830/// let slice = ['l', 'o', 'r', 'e', 'm'];1831/// let mut iter = slice.chunks_exact(2);1832/// assert_eq!(iter.next(), Some(&['l', 'o'][..]));1833/// assert_eq!(iter.next(), Some(&['r', 'e'][..]));1834/// assert_eq!(iter.next(), None);1835/// ```1836///1837/// [`chunks_exact`]: slice::chunks_exact1838/// [`remainder`]: ChunksExact::remainder1839/// [slices]: slice1840#[derive(Debug)]1841#[stable(feature = "chunks_exact", since = "1.31.0")]1842#[must_use = "iterators are lazy and do nothing unless consumed"]1843pub struct ChunksExact<'a, T: 'a> {1844    v: &'a [T],1845    rem: &'a [T],1846    chunk_size: usize,1847}18481849impl<'a, T> ChunksExact<'a, T> {1850    #[inline]1851    pub(super) const fn new(slice: &'a [T], chunk_size: usize) -> Self {1852        let rem = slice.len() % chunk_size;1853        let fst_len = slice.len() - rem;1854        // SAFETY: 0 <= fst_len <= slice.len() by construction above1855        let (fst, snd) = unsafe { slice.split_at_unchecked(fst_len) };1856        Self { v: fst, rem: snd, chunk_size }1857    }18581859    /// Returns the remainder of the original slice that is not going to be1860    /// returned by the iterator. The returned slice has at most `chunk_size-1`1861    /// elements.1862    ///1863    /// # Example1864    ///1865    /// ```1866    /// let slice = ['l', 'o', 'r', 'e', 'm'];1867    /// let mut iter = slice.chunks_exact(2);1868    /// assert_eq!(iter.remainder(), &['m'][..]);1869    /// assert_eq!(iter.next(), Some(&['l', 'o'][..]));1870    /// assert_eq!(iter.remainder(), &['m'][..]);1871    /// assert_eq!(iter.next(), Some(&['r', 'e'][..]));1872    /// assert_eq!(iter.remainder(), &['m'][..]);1873    /// assert_eq!(iter.next(), None);1874    /// assert_eq!(iter.remainder(), &['m'][..]);1875    /// ```1876    #[must_use]1877    #[stable(feature = "chunks_exact", since = "1.31.0")]1878    pub fn remainder(&self) -> &'a [T] {1879        self.rem1880    }1881}18821883// FIXME(#26925) Remove in favor of `#[derive(Clone)]`1884#[stable(feature = "chunks_exact", since = "1.31.0")]1885impl<T> Clone for ChunksExact<'_, T> {1886    fn clone(&self) -> Self {1887        ChunksExact { v: self.v, rem: self.rem, chunk_size: self.chunk_size }1888    }1889}18901891#[stable(feature = "chunks_exact", since = "1.31.0")]1892impl<'a, T> Iterator for ChunksExact<'a, T> {1893    type Item = &'a [T];18941895    #[inline]1896    fn next(&mut self) -> Option<&'a [T]> {1897        self.v.split_at_checked(self.chunk_size).and_then(|(chunk, rest)| {1898            self.v = rest;1899            Some(chunk)1900        })1901    }19021903    #[inline]1904    fn size_hint(&self) -> (usize, Option<usize>) {1905        let n = self.v.len() / self.chunk_size;1906        (n, Some(n))1907    }19081909    #[inline]1910    fn count(self) -> usize {1911        self.len()1912    }19131914    #[inline]1915    fn nth(&mut self, n: usize) -> Option<Self::Item> {1916        if let Some(start) = n.checked_mul(self.chunk_size)1917            && start < self.v.len()1918        {1919            self.v = &self.v[start..];1920            self.next()1921        } else {1922            self.v = &self.v[..0]; // cheaper than &[]1923            None1924        }1925    }19261927    #[inline]1928    fn last(mut self) -> Option<Self::Item> {1929        self.next_back()1930    }19311932    unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {1933        let start = idx * self.chunk_size;1934        // SAFETY: mostly identical to `Chunks::__iterator_get_unchecked`.1935        unsafe { from_raw_parts(self.v.as_ptr().add(start), self.chunk_size) }1936    }1937}19381939#[stable(feature = "chunks_exact", since = "1.31.0")]1940impl<'a, T> DoubleEndedIterator for ChunksExact<'a, T> {1941    #[inline]1942    fn next_back(&mut self) -> Option<&'a [T]> {1943        if self.v.len() < self.chunk_size {1944            None1945        } else {1946            let (fst, snd) = self.v.split_at(self.v.len() - self.chunk_size);1947            self.v = fst;1948            Some(snd)1949        }1950    }19511952    #[inline]1953    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {1954        let len = self.len();1955        if n < len {1956            let start = (len - 1 - n) * self.chunk_size;1957            let end = start + self.chunk_size;1958            let nth_back = &self.v[start..end];1959            self.v = &self.v[..start];1960            Some(nth_back)1961        } else {1962            self.v = &self.v[..0]; // cheaper than &[]1963            None1964        }1965    }1966}19671968#[stable(feature = "chunks_exact", since = "1.31.0")]1969impl<T> ExactSizeIterator for ChunksExact<'_, T> {1970    fn is_empty(&self) -> bool {1971        self.v.is_empty()1972    }1973}19741975#[unstable(feature = "trusted_len", issue = "37572")]1976unsafe impl<T> TrustedLen for ChunksExact<'_, T> {}19771978#[stable(feature = "chunks_exact", since = "1.31.0")]1979impl<T> FusedIterator for ChunksExact<'_, T> {}19801981#[doc(hidden)]1982#[unstable(feature = "trusted_random_access", issue = "none")]1983unsafe impl<'a, T> TrustedRandomAccess for ChunksExact<'a, T> {}19841985#[doc(hidden)]1986#[unstable(feature = "trusted_random_access", issue = "none")]1987unsafe impl<'a, T> TrustedRandomAccessNoCoerce for ChunksExact<'a, T> {1988    const MAY_HAVE_SIDE_EFFECT: bool = false;1989}19901991/// An iterator over a slice in (non-overlapping) mutable chunks (`chunk_size`1992/// elements at a time), starting at the beginning of the slice.1993///1994/// When the slice len is not evenly divided by the chunk size, the last up to1995/// `chunk_size-1` elements will be omitted but can be retrieved from the1996/// [`into_remainder`] function from the iterator.1997///1998/// This struct is created by the [`chunks_exact_mut`] method on [slices].1999///2000/// # Example