Improve design of assert_len

Author: dylni

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

@@ -1063,7 +1063,7 @@ impl<T> VecDeque<T> {
     where
         R: RangeBounds<usize>,
     {
-        let Range { start, end } = range.assert_len(self.len());
+        let Range { start, end } = range.ensure_subset_of(..self.len());
         let tail = self.wrap_add(self.tail, start);
         let head = self.wrap_add(self.tail, end);
         (tail, head)

library/alloc/src/lib.rs

@@ -112,7 +112,7 @@
 #![feature(or_patterns)]
 #![feature(pattern)]
 #![feature(ptr_internals)]
-#![feature(range_bounds_assert_len)]
+#![feature(range_bounds_ensure_subset_of)]
 #![feature(rustc_attrs)]
 #![feature(receiver_trait)]
 #![cfg_attr(bootstrap, feature(min_const_generics))]

library/alloc/src/string.rs

@@ -1510,14 +1510,14 @@ impl String {
         // of the vector 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 } = range.assert_len(self.len());
+        let Range { start, end } = range.ensure_subset_of(..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: `assert_len` and `is_char_boundary` do the appropriate bounds checks.
+        // SAFETY: `ensure_subset_of` 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 }

library/alloc/src/vec/mod.rs

@@ -1597,7 +1597,7 @@ impl<T, A: Allocator> Vec<T, A> {
         // the hole, and the vector length is restored to the new length.
         //
         let len = self.len();
-        let Range { start, end } = range.assert_len(len);
+        let Range { start, end } = range.ensure_subset_of(..len);
 
         unsafe {
             // set self.vec length's to start, to be safe in case Drain is leaked

library/core/src/ops/range.rs

@@ -766,8 +766,15 @@ pub trait RangeBounds<T: ?Sized> {
 
     /// Performs bounds-checking of this range.
     ///
+    /// This method is similar to [`Index::index`] for slices, but it returns a
+    /// [`Range`] equivalent to this range. You can use this method to turn any
+    /// range into `start` and `end` values.
+    ///
+    /// The given range is the range of the slice to use for bounds-checking. It
+    /// should be a [`RangeTo`] range that ends at the length of the slice.
+    ///
     /// The returned [`Range`] is safe to pass to [`slice::get_unchecked`] and
-    /// [`slice::get_unchecked_mut`] for slices of the given length.
+    /// [`slice::get_unchecked_mut`] for slices with the given range.
     ///
     /// [`slice::get_unchecked`]: ../../std/primitive.slice.html#method.get_unchecked
     /// [`slice::get_unchecked_mut`]: ../../std/primitive.slice.html#method.get_unchecked_mut
@@ -779,49 +786,51 @@ pub trait RangeBounds<T: ?Sized> {
     /// # Examples
     ///
     /// ```
-    /// #![feature(range_bounds_assert_len)]
+    /// #![feature(range_bounds_ensure_subset_of)]
     ///
     /// use std::ops::RangeBounds;
     ///
     /// let v = [10, 40, 30];
-    /// assert_eq!(1..2, (1..2).assert_len(v.len()));
-    /// assert_eq!(0..2, (..2).assert_len(v.len()));
-    /// assert_eq!(1..3, (1..).assert_len(v.len()));
+    /// assert_eq!(1..2, (1..2).ensure_subset_of(..v.len()));
+    /// assert_eq!(0..2, (..2).ensure_subset_of(..v.len()));
+    /// assert_eq!(1..3, (1..).ensure_subset_of(..v.len()));
     /// ```
     ///
     /// Panics when [`Index::index`] would panic:
     ///
     /// ```should_panic
-    /// #![feature(range_bounds_assert_len)]
+    /// #![feature(range_bounds_ensure_subset_of)]
     ///
     /// use std::ops::RangeBounds;
     ///
-    /// (2..1).assert_len(3);
+    /// (2..1).ensure_subset_of(..3);
     /// ```
     ///
     /// ```should_panic
-    /// #![feature(range_bounds_assert_len)]
+    /// #![feature(range_bounds_ensure_subset_of)]
     ///
     /// use std::ops::RangeBounds;
     ///
-    /// (1..4).assert_len(3);
+    /// (1..4).ensure_subset_of(..3);
     /// ```
     ///
     /// ```should_panic
-    /// #![feature(range_bounds_assert_len)]
+    /// #![feature(range_bounds_ensure_subset_of)]
     ///
     /// use std::ops::RangeBounds;
     ///
-    /// (1..=usize::MAX).assert_len(3);
+    /// (1..=usize::MAX).ensure_subset_of(..3);
     /// ```
     ///
     /// [`Index::index`]: crate::ops::Index::index
     #[track_caller]
-    #[unstable(feature = "range_bounds_assert_len", issue = "76393")]
-    fn assert_len(self, len: usize) -> Range<usize>
+    #[unstable(feature = "range_bounds_ensure_subset_of", issue = "76393")]
+    fn ensure_subset_of(self, range: RangeTo<usize>) -> Range<usize>
     where
         Self: RangeBounds<usize>,
     {
+        let len = range.end;
+
         let start: Bound<&usize> = self.start_bound();
         let start = match start {
             Bound::Included(&start) => start,

library/core/src/slice/mod.rs

@@ -3052,7 +3052,7 @@ impl<T> [T] {
     where
         T: Copy,
     {
-        let Range { start: src_start, end: src_end } = src.assert_len(self.len());
+        let Range { start: src_start, end: src_end } = src.ensure_subset_of(..self.len());
         let count = src_end - src_start;
         assert!(dest <= self.len() - count, "dest is out of bounds");
         // SAFETY: the conditions for `ptr::copy` have all been checked above,

src/doc/unstable-book/src/library-features/range-bounds-assert-len.md

@@ -0,0 +1,10 @@
+# `range_bounds_ensure_subset_of`
+
+The tracking issue for this feature is: [#76393]
+
+------------------------
+
+This adds [`RangeBounds::ensure_subset_of`].
+
+[#76393]: https://github.com/rust-lang/rust/issues/76393
+[`RangeBounds::ensure_subset_of`]: https://doc.rust-lang.org/nightly/std/ops/trait.RangeBounds.html#method.ensure_subset_of