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