Rollup merge of rust-lang#144765 - Qelxiros:range-inclusive-last, r=jhpratt

inclusive `Range`s: change `end` to `last`

Tracking issue: rust-lang#125687
ACP: rust-lang/libs-team#511

Author: matthiaskrgr

core/src/range.rs

@@ -31,9 +31,7 @@ pub use iter::{IterRange, IterRangeFrom, IterRangeInclusive};
 #[doc(inline)]
 pub use crate::iter::Step;
 #[doc(inline)]
-pub use crate::ops::{
-    Bound, IntoBounds, OneSidedRange, RangeBounds, RangeFull, RangeTo, RangeToInclusive,
-};
+pub use crate::ops::{Bound, IntoBounds, OneSidedRange, RangeBounds, RangeFull, RangeTo};
 
 /// A (half-open) range bounded inclusively below and exclusively above
 /// (`start..end` in a future edition).
@@ -209,20 +207,20 @@ impl<T> const From<legacy::Range<T>> for Range<T> {
     }
 }
 
-/// A range bounded inclusively below and above (`start..=end`).
+/// A range bounded inclusively below and above (`start..=last`).
 ///
-/// The `RangeInclusive` `start..=end` contains all values with `x >= start`
-/// and `x <= end`. It is empty unless `start <= end`.
+/// The `RangeInclusive` `start..=last` contains all values with `x >= start`
+/// and `x <= last`. It is empty unless `start <= last`.
 ///
 /// # Examples
 ///
-/// The `start..=end` syntax is a `RangeInclusive`:
+/// The `start..=last` syntax is a `RangeInclusive`:
 ///
 /// ```
 /// #![feature(new_range_api)]
 /// use core::range::RangeInclusive;
 ///
-/// assert_eq!(RangeInclusive::from(3..=5), RangeInclusive { start: 3, end: 5 });
+/// assert_eq!(RangeInclusive::from(3..=5), RangeInclusive { start: 3, last: 5 });
 /// assert_eq!(3 + 4 + 5, RangeInclusive::from(3..=5).into_iter().sum());
 /// ```
 #[lang = "RangeInclusiveCopy"]
@@ -234,15 +232,15 @@ pub struct RangeInclusive<Idx> {
     pub start: Idx,
     /// The upper bound of the range (inclusive).
     #[unstable(feature = "new_range_api", issue = "125687")]
-    pub end: Idx,
+    pub last: Idx,
 }
 
 #[unstable(feature = "new_range_api", issue = "125687")]
 impl<Idx: fmt::Debug> fmt::Debug for RangeInclusive<Idx> {
     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
         self.start.fmt(fmt)?;
         write!(fmt, "..=")?;
-        self.end.fmt(fmt)?;
+        self.last.fmt(fmt)?;
         Ok(())
     }
 }
@@ -306,7 +304,7 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
     #[unstable(feature = "new_range_api", issue = "125687")]
     #[inline]
     pub fn is_empty(&self) -> bool {
-        !(self.start <= self.end)
+        !(self.start <= self.last)
     }
 }
 
@@ -335,10 +333,10 @@ impl<Idx: Step> RangeInclusive<Idx> {
 
 impl RangeInclusive<usize> {
     /// Converts to an exclusive `Range` for `SliceIndex` implementations.
-    /// The caller is responsible for dealing with `end == usize::MAX`.
+    /// The caller is responsible for dealing with `last == usize::MAX`.
     #[inline]
     pub(crate) const fn into_slice_range(self) -> Range<usize> {
-        Range { start: self.start, end: self.end + 1 }
+        Range { start: self.start, end: self.last + 1 }
     }
 }
 
@@ -348,7 +346,7 @@ impl<T> RangeBounds<T> for RangeInclusive<T> {
         Included(&self.start)
     }
     fn end_bound(&self) -> Bound<&T> {
-        Included(&self.end)
+        Included(&self.last)
     }
 }
 
@@ -364,15 +362,15 @@ impl<T> RangeBounds<T> for RangeInclusive<&T> {
         Included(self.start)
     }
     fn end_bound(&self) -> Bound<&T> {
-        Included(self.end)
+        Included(self.last)
     }
 }
 
 // #[unstable(feature = "range_into_bounds", issue = "136903")]
 #[unstable(feature = "new_range_api", issue = "125687")]
 impl<T> IntoBounds<T> for RangeInclusive<T> {
     fn into_bounds(self) -> (Bound<T>, Bound<T>) {
-        (Included(self.start), Included(self.end))
+        (Included(self.start), Included(self.last))
     }
 }
 
@@ -381,7 +379,7 @@ impl<T> IntoBounds<T> for RangeInclusive<T> {
 impl<T> const From<RangeInclusive<T>> for legacy::RangeInclusive<T> {
     #[inline]
     fn from(value: RangeInclusive<T>) -> Self {
-        Self::new(value.start, value.end)
+        Self::new(value.start, value.last)
     }
 }
 #[unstable(feature = "new_range_api", issue = "125687")]
@@ -394,8 +392,8 @@ impl<T> const From<legacy::RangeInclusive<T>> for RangeInclusive<T> {
             "attempted to convert from an exhausted `legacy::RangeInclusive` (unspecified behavior)"
         );
 
-        let (start, end) = value.into_inner();
-        RangeInclusive { start, end }
+        let (start, last) = value.into_inner();
+        RangeInclusive { start, last }
     }
 }
 
@@ -544,3 +542,107 @@ impl<T> const From<legacy::RangeFrom<T>> for RangeFrom<T> {
         Self { start: value.start }
     }
 }
+
+/// A range only bounded inclusively above (`..=last`).
+///
+/// The `RangeToInclusive` `..=last` contains all values with `x <= last`.
+/// It cannot serve as an [`Iterator`] because it doesn't have a starting point.
+///
+/// # Examples
+///
+/// The `..=last` syntax is a `RangeToInclusive`:
+///
+/// ```
+/// #![feature(new_range_api)]
+/// #![feature(new_range)]
+/// assert_eq!((..=5), std::range::RangeToInclusive{ last: 5 });
+/// ```
+///
+/// It does not have an [`IntoIterator`] implementation, so you can't use it in a
+/// `for` loop directly. This won't compile:
+///
+/// ```compile_fail,E0277
+/// // error[E0277]: the trait bound `std::range::RangeToInclusive<{integer}>:
+/// // std::iter::Iterator` is not satisfied
+/// for i in ..=5 {
+///     // ...
+/// }
+/// ```
+///
+/// When used as a [slicing index], `RangeToInclusive` produces a slice of all
+/// array elements up to and including the index indicated by `last`.
+///
+/// ```
+/// let arr = [0, 1, 2, 3, 4];
+/// assert_eq!(arr[ ..  ], [0, 1, 2, 3, 4]);
+/// assert_eq!(arr[ .. 3], [0, 1, 2      ]);
+/// assert_eq!(arr[ ..=3], [0, 1, 2, 3   ]); // This is a `RangeToInclusive`
+/// assert_eq!(arr[1..  ], [   1, 2, 3, 4]);
+/// assert_eq!(arr[1.. 3], [   1, 2      ]);
+/// assert_eq!(arr[1..=3], [   1, 2, 3   ]);
+/// ```
+///
+/// [slicing index]: crate::slice::SliceIndex
+#[lang = "RangeToInclusiveCopy"]
+#[doc(alias = "..=")]
+#[derive(Copy, Clone, PartialEq, Eq, Hash)]
+#[unstable(feature = "new_range_api", issue = "125687")]
+pub struct RangeToInclusive<Idx> {
+    /// The upper bound of the range (inclusive)
+    #[unstable(feature = "new_range_api", issue = "125687")]
+    pub last: Idx,
+}
+
+#[unstable(feature = "new_range_api", issue = "125687")]
+impl<Idx: fmt::Debug> fmt::Debug for RangeToInclusive<Idx> {
+    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(fmt, "..=")?;
+        self.last.fmt(fmt)?;
+        Ok(())
+    }
+}
+
+impl<Idx: PartialOrd<Idx>> RangeToInclusive<Idx> {
+    /// Returns `true` if `item` is contained in the range.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// assert!( (..=5).contains(&-1_000_000_000));
+    /// assert!( (..=5).contains(&5));
+    /// assert!(!(..=5).contains(&6));
+    ///
+    /// assert!( (..=1.0).contains(&1.0));
+    /// assert!(!(..=1.0).contains(&f32::NAN));
+    /// assert!(!(..=f32::NAN).contains(&0.5));
+    /// ```
+    #[inline]
+    #[unstable(feature = "new_range_api", issue = "125687")]
+    pub fn contains<U>(&self, item: &U) -> bool
+    where
+        Idx: PartialOrd<U>,
+        U: ?Sized + PartialOrd<Idx>,
+    {
+        <Self as RangeBounds<Idx>>::contains(self, item)
+    }
+}
+
+// RangeToInclusive<Idx> cannot impl From<RangeTo<Idx>>
+// because underflow would be possible with (..0).into()
+
+#[unstable(feature = "new_range_api", issue = "125687")]
+impl<T> RangeBounds<T> for RangeToInclusive<T> {
+    fn start_bound(&self) -> Bound<&T> {
+        Unbounded
+    }
+    fn end_bound(&self) -> Bound<&T> {
+        Included(&self.last)
+    }
+}
+
+#[unstable(feature = "range_into_bounds", issue = "136903")]
+impl<T> IntoBounds<T> for RangeToInclusive<T> {
+    fn into_bounds(self) -> (Bound<T>, Bound<T>) {
+        (Unbounded, Included(self.last))
+    }
+}

core/src/range/iter.rs

@@ -164,7 +164,7 @@ impl<A: Step> IterRangeInclusive<A> {
             return None;
         }
 
-        Some(RangeInclusive { start: self.0.start, end: self.0.end })
+        Some(RangeInclusive { start: self.0.start, last: self.0.end })
     }
 }
 

core/src/range/legacy.rs

@@ -1,10 +1,10 @@
 //! # Legacy range types
 //!
 //! The types within this module will be replaced by the types
-//! [`Range`], [`RangeInclusive`], and [`RangeFrom`] in the parent
+//! [`Range`], [`RangeInclusive`], [`RangeToInclusive`], and [`RangeFrom`] in the parent
 //! module, [`core::range`].
 //!
 //! The types here are equivalent to those in [`core::ops`].
 
 #[doc(inline)]
-pub use crate::ops::{Range, RangeFrom, RangeInclusive};
+pub use crate::ops::{Range, RangeFrom, RangeInclusive, RangeToInclusive};

core/src/slice/index.rs

@@ -129,6 +129,8 @@ mod private_slice_index {
     #[unstable(feature = "new_range_api", issue = "125687")]
     impl Sealed for range::RangeInclusive<usize> {}
     #[unstable(feature = "new_range_api", issue = "125687")]
+    impl Sealed for range::RangeToInclusive<usize> {}
+    #[unstable(feature = "new_range_api", issue = "125687")]
     impl Sealed for range::RangeFrom<usize> {}
 
     impl Sealed for ops::IndexRange {}
@@ -788,6 +790,45 @@ unsafe impl<T> const SliceIndex<[T]> for ops::RangeToInclusive<usize> {
     }
 }
 
+/// The methods `index` and `index_mut` panic if the end of the range is out of bounds.
+#[stable(feature = "inclusive_range", since = "1.26.0")]
+#[rustc_const_unstable(feature = "const_index", issue = "143775")]
+unsafe impl<T> const SliceIndex<[T]> for range::RangeToInclusive<usize> {
+    type Output = [T];
+
+    #[inline]
+    fn get(self, slice: &[T]) -> Option<&[T]> {
+        (0..=self.last).get(slice)
+    }
+
+    #[inline]
+    fn get_mut(self, slice: &mut [T]) -> Option<&mut [T]> {
+        (0..=self.last).get_mut(slice)
+    }
+
+    #[inline]
+    unsafe fn get_unchecked(self, slice: *const [T]) -> *const [T] {
+        // SAFETY: the caller has to uphold the safety contract for `get_unchecked`.
+        unsafe { (0..=self.last).get_unchecked(slice) }
+    }
+
+    #[inline]
+    unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut [T] {
+        // SAFETY: the caller has to uphold the safety contract for `get_unchecked_mut`.
+        unsafe { (0..=self.last).get_unchecked_mut(slice) }
+    }
+
+    #[inline]
+    fn index(self, slice: &[T]) -> &[T] {
+        (0..=self.last).index(slice)
+    }
+
+    #[inline]
+    fn index_mut(self, slice: &mut [T]) -> &mut [T] {
+        (0..=self.last).index_mut(slice)
+    }
+}
+
 /// Performs bounds checking of a range.
 ///
 /// This method is similar to [`Index::index`] for slices, but it returns a

core/src/str/traits.rs

@@ -677,11 +677,11 @@ unsafe impl const SliceIndex<str> for range::RangeInclusive<usize> {
     type Output = str;
     #[inline]
     fn get(self, slice: &str) -> Option<&Self::Output> {
-        if self.end == usize::MAX { None } else { self.into_slice_range().get(slice) }
+        if self.last == usize::MAX { None } else { self.into_slice_range().get(slice) }
     }
     #[inline]
     fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
-        if self.end == usize::MAX { None } else { self.into_slice_range().get_mut(slice) }
+        if self.last == usize::MAX { None } else { self.into_slice_range().get_mut(slice) }
     }
     #[inline]
     unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output {
@@ -695,14 +695,14 @@ unsafe impl const SliceIndex<str> for range::RangeInclusive<usize> {
     }
     #[inline]
     fn index(self, slice: &str) -> &Self::Output {
-        if self.end == usize::MAX {
+        if self.last == usize::MAX {
             str_index_overflow_fail();
         }
         self.into_slice_range().index(slice)
     }
     #[inline]
     fn index_mut(self, slice: &mut str) -> &mut Self::Output {
-        if self.end == usize::MAX {
+        if self.last == usize::MAX {
             str_index_overflow_fail();
         }
         self.into_slice_range().index_mut(slice)