Add Vec::drain and String::drain.

CHANGELOG.md

@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Added `IntoIterator` implementation for `LinearMap`
 - Added `Deque::{get, get_mut, get_unchecked, get_unchecked_mut}`.
 - Added `serde::Serialize` and `serde::Deserialize` implementations to `HistoryBuffer`.
+- Added `Vec::drain`.
+- Added `String::drain`.
 
 ### Changed
 

src/lib.rs

@@ -96,6 +96,7 @@ pub use indexmap::{
 pub use indexset::{FnvIndexSet, IndexSet, Iter as IndexSetIter};
 pub use linear_map::LinearMap;
 pub use string::String;
+
 pub use vec::{Vec, VecView};
 
 #[macro_use]
@@ -107,6 +108,7 @@ mod histbuf;
 mod indexmap;
 mod indexset;
 mod linear_map;
+mod slice;
 pub mod storage;
 pub mod string;
 pub mod vec;

src/slice.rs

@@ -0,0 +1,38 @@
+use core::ops;
+
+// FIXME: Remove when `slice_range` feature is stable.
+#[track_caller]
+#[must_use]
+pub fn range<R>(range: R, bounds: ops::RangeTo<usize>) -> ops::Range<usize>
+where
+    R: ops::RangeBounds<usize>,
+{
+    let len = bounds.end;
+
+    let start: ops::Bound<&usize> = range.start_bound();
+    let start = match start {
+        ops::Bound::Included(&start) => start,
+        ops::Bound::Excluded(start) => start
+            .checked_add(1)
+            .unwrap_or_else(|| panic!("attempted to index slice from after maximum usize")),
+        ops::Bound::Unbounded => 0,
+    };
+
+    let end: ops::Bound<&usize> = range.end_bound();
+    let end = match end {
+        ops::Bound::Included(end) => end
+            .checked_add(1)
+            .unwrap_or_else(|| panic!("attempted to index slice up to maximum usize")),
+        ops::Bound::Excluded(&end) => end,
+        ops::Bound::Unbounded => len,
+    };
+
+    if start > end {
+        panic!("slice index starts at {start} but ends at {end}");
+    }
+    if end > len {
+        panic!("range end index {end} out of range for slice of length {len}");
+    }
+
+    ops::Range { start, end }
+}

src/string/drain.rs

@@ -0,0 +1,134 @@
+use core::{fmt, iter::FusedIterator, str::Chars};
+
+use super::String;
+
+/// A draining iterator for `String`.
+///
+/// This struct is created by the [`drain`] method on [`String`]. See its
+/// documentation for more.
+///
+/// [`drain`]: String::drain
+pub struct Drain<'a, const N: usize> {
+    /// Will be used as &'a mut String in the destructor
+    pub(super) string: *mut String<N>,
+    /// Start of part to remove
+    pub(super) start: usize,
+    /// End of part to remove
+    pub(super) end: usize,
+    /// Current remaining range to remove
+    pub(super) iter: Chars<'a>,
+}
+
+impl<const N: usize> fmt::Debug for Drain<'_, N> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_tuple("Drain").field(&self.as_str()).finish()
+    }
+}
+
+unsafe impl<const N: usize> Sync for Drain<'_, N> {}
+unsafe impl<const N: usize> Send for Drain<'_, N> {}
+
+impl<const N: usize> Drop for Drain<'_, N> {
+    fn drop(&mut self) {
+        unsafe {
+            // Use `Vec::drain`. “Reaffirm” the bounds checks to avoid
+            // panic code being inserted again.
+            let self_vec = (*self.string).as_mut_vec();
+            if self.start <= self.end && self.end <= self_vec.len() {
+                self_vec.drain(self.start..self.end);
+            }
+        }
+    }
+}
+
+impl<'a, const N: usize> Drain<'a, N> {
+    /// Returns the remaining (sub)string of this iterator as a slice.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use heapless::String;
+    ///
+    /// let mut s = String::<8>::try_from("abc").unwrap();
+    /// let mut drain = s.drain(..);
+    /// assert_eq!(drain.as_str(), "abc");
+    /// let _ = drain.next().unwrap();
+    /// assert_eq!(drain.as_str(), "bc");
+    /// ```
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        self.iter.as_str()
+    }
+}
+
+impl<const N: usize> AsRef<str> for Drain<'_, N> {
+    fn as_ref(&self) -> &str {
+        self.as_str()
+    }
+}
+
+impl<const N: usize> AsRef<[u8]> for Drain<'_, N> {
+    fn as_ref(&self) -> &[u8] {
+        self.as_str().as_bytes()
+    }
+}
+
+impl<const N: usize> Iterator for Drain<'_, N> {
+    type Item = char;
+
+    #[inline]
+    fn next(&mut self) -> Option<char> {
+        self.iter.next()
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.iter.size_hint()
+    }
+
+    #[inline]
+    fn last(mut self) -> Option<char> {
+        self.next_back()
+    }
+}
+
+impl<const N: usize> DoubleEndedIterator for Drain<'_, N> {
+    #[inline]
+    fn next_back(&mut self) -> Option<char> {
+        self.iter.next_back()
+    }
+}
+
+impl<const N: usize> FusedIterator for Drain<'_, N> {}
+
+#[cfg(test)]
+mod tests {
+    use super::String;
+
+    #[test]
+    fn drain_front() {
+        let mut s = String::<8>::try_from("abcd").unwrap();
+        let mut it = s.drain(..1);
+        assert_eq!(it.next(), Some('a'));
+        drop(it);
+        assert_eq!(s, "bcd");
+    }
+
+    #[test]
+    fn drain_middle() {
+        let mut s = String::<8>::try_from("abcd").unwrap();
+        let mut it = s.drain(1..3);
+        assert_eq!(it.next(), Some('b'));
+        assert_eq!(it.next(), Some('c'));
+        drop(it);
+        assert_eq!(s, "ad");
+    }
+
+    #[test]
+    fn drain_end() {
+        let mut s = String::<8>::try_from("abcd").unwrap();
+        let mut it = s.drain(3..);
+        assert_eq!(it.next(), Some('d'));
+        drop(it);
+        assert_eq!(s, "abc");
+    }
+}

src/string.rs → src/string/mod.rs

@@ -5,12 +5,16 @@ use core::{
     cmp::Ordering,
     fmt,
     fmt::{Arguments, Write},
-    hash, iter, ops,
+    hash, iter,
+    ops::{self, Range, RangeBounds},
     str::{self, Utf8Error},
 };
 
 use crate::Vec;
 
+mod drain;
+pub use drain::Drain;
+
 /// A possible error value when converting a [`String`] from a UTF-16 byte slice.
 ///
 /// This type is the error type for the [`from_utf16`] method on [`String`].
@@ -456,6 +460,69 @@ impl<const N: usize> String<N> {
     pub fn clear(&mut self) {
         self.vec.clear()
     }
+
+    /// Removes the specified range from the string in bulk, returning all
+    /// removed characters as an iterator.
+    ///
+    /// The returned iterator keeps a mutable borrow on the string to optimize
+    /// its implementation.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the starting point or end point do not lie on a [`char`]
+    /// boundary, or if they're out of bounds.
+    ///
+    /// # Leaking
+    ///
+    /// If the returned iterator goes out of scope without being dropped (due to
+    /// [`core::mem::forget`], for example), the string may still contain a copy
+    /// of any drained characters, or may have lost characters arbitrarily,
+    /// including characters outside the range.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use heapless::String;
+    ///
+    /// let mut s = String::<32>::try_from("α is alpha, β is beta").unwrap();
+    /// let beta_offset = s.find('β').unwrap_or(s.len());
+    ///
+    /// // Remove the range up until the β from the string
+    /// let t: String<32> = s.drain(..beta_offset).collect();
+    /// assert_eq!(t, "α is alpha, ");
+    /// assert_eq!(s, "β is beta");
+    ///
+    /// // A full range clears the string, like `clear()` does
+    /// s.drain(..);
+    /// assert_eq!(s, "");
+    /// ```
+    pub fn drain<R>(&mut self, range: R) -> Drain<'_, N>
+    where
+        R: RangeBounds<usize>,
+    {
+        // Memory safety
+        //
+        // The `String` version of `Drain` does not have the memory safety issues
+        // of the `Vec` version. The data is just plain bytes.
+        // Because the range removal happens in `Drop`, if the `Drain` iterator is leaked,
+        // the removal will not happen.
+        let Range { start, end } = crate::slice::range(range, ..self.len());
+        assert!(self.is_char_boundary(start));
+        assert!(self.is_char_boundary(end));
+
+        // Take out two simultaneous borrows. The &mut String won't be accessed
+        // until iteration is over, in Drop.
+        let self_ptr = self as *mut _;
+        // SAFETY: `slice::range` and `is_char_boundary` do the appropriate bounds checks.
+        let chars_iter = unsafe { self.get_unchecked(start..end) }.chars();
+
+        Drain {
+            start,
+            end,
+            iter: chars_iter,
+            string: self_ptr,
+        }
+    }
 }
 
 impl<const N: usize> Default for String<N> {