Stabilize new inclusive range type and iterator type

[pitaj]

Part 1 of stabilizing the new range types for #125687

stabilizes core::range::RangeInclusive and core::range::RangeInclusiveIter. Newly stable API:

// in core and std
mod range;

// in core::range

pub struct RangeInclusive<Idx> {
    pub start: Idx,
    pub last: Idx,
}

impl<Idx: fmt::Debug> fmt::Debug for RangeInclusive<Idx> { /* ... */ }

impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
    pub const fn contains<U>(&self, item: &U) -> bool
    where
        Idx: [const] PartialOrd<U>,
        U: ?Sized + [const] PartialOrd<Idx>;

    pub const fn is_empty(&self) -> bool
    where
        Idx: [const] PartialOrd;
}

impl<Idx: Step> RangeInclusive<Idx> {
    pub fn iter(&self) -> RangeInclusiveIter<Idx>;
}

impl<T> const RangeBounds<T> for RangeInclusive<T> { /* ... */ }
impl<T> const RangeBounds<T> for RangeInclusive<&T> { /* ... */ }

impl<T> const From<RangeInclusive<T>> for legacy::RangeInclusive<T> { /* ... */ }
impl<T> const From<legacy::RangeInclusive<T>> for RangeInclusive<T> { /* ... */ }

pub struct RangeInclusiveIter<A>(/* ... */);

impl<A: Step> RangeInclusiveIter<A> {
    pub fn remainder(self) -> Option<RangeInclusive<A>>;
}

impl<A: Step> Iterator for RangeInclusiveIter<A> {
    type Item = A;
    /* ... */
}

impl<A: Step> DoubleEndedIterator for RangeInclusiveIter<A> { /* ... */ }
impl<A: Step> FusedIterator for RangeInclusiveIter<A> { }
impl<A: Step> IntoIterator for RangeInclusive<A> {
    type Item = A;
    type IntoIter = RangeInclusiveIter<A>;
    /* ... */
}

impl ExactSizeIterator for RangeInclusiveIter<u8> { }
impl ExactSizeIterator for RangeInclusiveIter<i8> { }

unsafe impl<T> const SliceIndex<[T]> for range::RangeInclusive<usize> {
    type Output = [T];
    /* ... */
}
unsafe impl const SliceIndex<str> for range::RangeInclusive<usize> {
    type Output = str;
    /* ... */
}

I've removed the re-exports temporarily because from what I can tell, there's no way to make re-exports of stable items unstable. They will be added back and stabilized in a separate PR.

[rustbot]

r? @jackh726

rustbot has assigned @jackh726.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[jackh726]

r? libs-api

[tgross35]

Nit: FIXME(#125687) keeps things greppable (ditto for the FIXMEs in the tests)

[tgross35]

Optional nit: the camel->snake conversion from RangeInclusive would be range_inclusive rather than rangeinclusive

[tgross35]

These can be dropped from the doctests on stabilized API

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[tgross35]

@joshtriplett in the FCP proposal said

(Note that this doesn't include the is_empty method.)

I'm not sure what the context is, but should it be dropped?

[joshtriplett]

This is_empty is fine; we checked in the libs-api meeting, and we're pretty sure that comment was referring to the unstable method on RangeBounds, which we should not stabilize.

[tgross35]

I added an API summary of what is stabilized here to the top post, nominating for @rust-lang/libs-api to double check and nudge the FCP. There is an ongoing proposed FCP at #125687 (comment), but maybe it makes sense to restart it here with smaller scope?

Everything seems to match up with the traits available on ops::RangeInclusive, delta ExactSizeIterator for i16/u16 (expected as it is incorrect on 16-bit targets).

Two small concerns found from digging around the issue and other discussion:

• Stabilize new inclusive range type and iterator type #150522 (comment) is the intent to exclude is_empty for now?
• Field names are "start" and "last" which don't typically go together. It used to be "start" and "end" like for Range, but end was renamed at Rename end field of inclusive Range APIs to last libs-team#511 to avoid a footgun. Should we consider start->first so we have "first" and "last"?

@rustbot label +I-libs-api-nominated

[scottmcm]

Field names are "start" and "last" which don't typically go together. It used to be "start" and "end" like

TBH, I never thought "start" and "end" went together either. A race is start-to-finish where you place somewhere in first..=last; a story commonly has a beginning, middle, and end.

Are any of those better enough to bother changing something? Dunno.

[sendittothenewts]

Should we consider `start`->`first` so we have "first" and "last"?

When I suggested changing end to last on the inclusive ranges, it did occur to me that this would be more consistent. I didn't suggest this change because it would bring Range, RangeFrom and arguably RangeBounds::start_bound into the blast radius for little benefit. Also, there is no first method on iterators to be consistent with.

[Amanieu]

We discussed the field names in the @rust-lang/libs-api meeting and were inclined to keep them as they currently are.

[pitaj]

As they currently are in this PR, or as they currently are on the old RangeInclusive types?

[tgross35]

As they currently are in this PR, or as they currently are on the old RangeInclusive types?

I believe as they are in this PR. From the meeting notes at https://hackmd.io/_EpeHNVySbqHWCSqXwLX1w#nominated-rusttf150522-Stabilize-new-inclusive-range-type-and-iterator-type

Amanieu: I'm happy with "start" and "last". Any objections?
[...]
Josh: I'd ship the currently proposed API.

And no different names mentioned.