library/alloc/src/collections/vec_deque/iter_mut.rs

   1 use core::fmt;
   2 use core::iter::{FusedIterator, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce};
   3 use core::marker::PhantomData;
   4
   5 use super::{count, wrap_index, RingSlices};
   6
   7 /// A mutable iterator over the elements of a `VecDeque`.
   8 ///
   9 /// This `struct` is created by the [`iter_mut`] method on [`super::VecDeque`]. See its
  10 /// documentation for more.
  11 ///
  12 /// [`iter_mut`]: super::VecDeque::iter_mut
  13 #[stable(feature = "rust1", since = "1.0.0")]
  14 pub struct IterMut<'a, T: 'a> {
  15     // Internal safety invariant: the entire slice is dereferencable.
  16     pub(crate) ring: *mut [T],
  17     pub(crate) tail: usize,
  18     pub(crate) head: usize,
  19     pub(crate) phantom: PhantomData<&'a mut [T]>,
  20 }
  21
  22 // SAFETY: we do nothing thread-local and there is no interior mutability,
  23 // so the usual structural `Send`/`Sync` apply.
  24 #[stable(feature = "rust1", since = "1.0.0")]
  25 unsafe impl<T: Send> Send for IterMut<'_, T> {}
  26 #[stable(feature = "rust1", since = "1.0.0")]
  27 unsafe impl<T: Sync> Sync for IterMut<'_, T> {}
  28
  29 #[stable(feature = "collection_debug", since = "1.17.0")]
  30 impl<T: fmt::Debug> fmt::Debug for IterMut<'_, T> {
  31     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  32         let (front, back) = RingSlices::ring_slices(self.ring, self.head, self.tail);
  33         // SAFETY: these are the elements we have not handed out yet, so aliasing is fine.
  34         // The `IterMut` invariant also ensures everything is dereferencable.
  35         let (front, back) = unsafe { (&*front, &*back) };
  36         f.debug_tuple("IterMut").field(&front).field(&back).finish()
  37     }
  38 }
  39
  40 #[stable(feature = "rust1", since = "1.0.0")]
  41 impl<'a, T> Iterator for IterMut<'a, T> {
  42     type Item = &'a mut T;
  43
  44     #[inline]
  45     fn next(&mut self) -> Option<&'a mut T> {
  46         if self.tail == self.head {
  47             return None;
  48         }
  49         let tail = self.tail;
  50         self.tail = wrap_index(self.tail.wrapping_add(1), self.ring.len());
  51
  52         unsafe {
  53             let elem = self.ring.get_unchecked_mut(tail);
  54             Some(&mut *elem)
  55         }
  56     }
  57
  58     #[inline]
  59     fn size_hint(&self) -> (usize, Option<usize>) {
  60         let len = count(self.tail, self.head, self.ring.len());
  61         (len, Some(len))
  62     }
  63
  64     fn fold<Acc, F>(self, mut accum: Acc, mut f: F) -> Acc
  65     where
  66         F: FnMut(Acc, Self::Item) -> Acc,
  67     {
  68         let (front, back) = RingSlices::ring_slices(self.ring, self.head, self.tail);
  69         // SAFETY: these are the elements we have not handed out yet, so aliasing is fine.
  70         // The `IterMut` invariant also ensures everything is dereferencable.
  71         let (front, back) = unsafe { (&mut *front, &mut *back) };
  72         accum = front.iter_mut().fold(accum, &mut f);
  73         back.iter_mut().fold(accum, &mut f)
  74     }
  75
  76     fn nth(&mut self, n: usize) -> Option<Self::Item> {
  77         if n >= count(self.tail, self.head, self.ring.len()) {
  78             self.tail = self.head;
  79             None
  80         } else {
  81             self.tail = wrap_index(self.tail.wrapping_add(n), self.ring.len());
  82             self.next()
  83         }
  84     }
  85
  86     #[inline]
  87     fn last(mut self) -> Option<&'a mut T> {
  88         self.next_back()
  89     }
  90
  91     #[inline]
  92     #[doc(hidden)]
  93     unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item {
  94         // Safety: The TrustedRandomAccess contract requires that callers only pass an index
  95         // that is in bounds.
  96         unsafe {
  97             let idx = wrap_index(self.tail.wrapping_add(idx), self.ring.len());
  98             &mut *self.ring.get_unchecked_mut(idx)
  99         }
 100     }
 101 }
 102
 103 #[stable(feature = "rust1", since = "1.0.0")]
 104 impl<'a, T> DoubleEndedIterator for IterMut<'a, T> {
 105     #[inline]
 106     fn next_back(&mut self) -> Option<&'a mut T> {
 107         if self.tail == self.head {
 108             return None;
 109         }
 110         self.head = wrap_index(self.head.wrapping_sub(1), self.ring.len());
 111
 112         unsafe {
 113             let elem = self.ring.get_unchecked_mut(self.head);
 114             Some(&mut *elem)
 115         }
 116     }
 117
 118     fn rfold<Acc, F>(self, mut accum: Acc, mut f: F) -> Acc
 119     where
 120         F: FnMut(Acc, Self::Item) -> Acc,
 121     {
 122         let (front, back) = RingSlices::ring_slices(self.ring, self.head, self.tail);
 123         // SAFETY: these are the elements we have not handed out yet, so aliasing is fine.
 124         // The `IterMut` invariant also ensures everything is dereferencable.
 125         let (front, back) = unsafe { (&mut *front, &mut *back) };
 126         accum = back.iter_mut().rfold(accum, &mut f);
 127         front.iter_mut().rfold(accum, &mut f)
 128     }
 129 }
 130
 131 #[stable(feature = "rust1", since = "1.0.0")]
 132 impl<T> ExactSizeIterator for IterMut<'_, T> {
 133     fn is_empty(&self) -> bool {
 134         self.head == self.tail
 135     }
 136 }
 137
 138 #[stable(feature = "fused", since = "1.26.0")]
 139 impl<T> FusedIterator for IterMut<'_, T> {}
 140
 141 #[unstable(feature = "trusted_len", issue = "37572")]
 142 unsafe impl<T> TrustedLen for IterMut<'_, T> {}
 143
 144 #[doc(hidden)]
 145 #[unstable(feature = "trusted_random_access", issue = "none")]
 146 unsafe impl<T> TrustedRandomAccess for IterMut<'_, T> {}
 147
 148 #[doc(hidden)]
 149 #[unstable(feature = "trusted_random_access", issue = "none")]
 150 unsafe impl<T> TrustedRandomAccessNoCoerce for IterMut<'_, T> {
 151     const MAY_HAVE_SIDE_EFFECT: bool = false;
 152 }