Partially stabilize bound_as_ref by stabilizing Bound::as_ref

[lopopolo]

Stabilizing Bound::as_ref will simplify the implementation for RangeBounds<usize> for custom range types:

impl RangeBounds<usize> for Region {
    fn start_bound(&self) -> Bound<&usize> {
        // TODO: Use `self.start.as_ref()` when upstream `std` stabilizes:
        // https://github.com/rust-lang/rust/issues/80996
        match self.start {
            Bound::Included(ref bound) => Bound::Included(bound),
            Bound::Excluded(ref bound) => Bound::Excluded(bound),
            Bound::Unbounded => Bound::Unbounded,
        }
    }

    fn end_bound(&self) -> Bound<&usize> {
        // TODO: Use `self.end.as_ref()` when upstream `std` stabilizes:
        // https://github.com/rust-lang/rust/issues/80996
        match self.end {
            Bound::Included(ref bound) => Bound::Included(bound),
            Bound::Excluded(ref bound) => Bound::Excluded(bound),
            Bound::Unbounded => Bound::Unbounded,
        }
    }
}

See:

• Tracking Issue for bound_as_ref #80996
• Tracking Issue for bound_as_ref #80996 (comment)

cc @yaahc who suggested partial stabilization.

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[rust-highfive]

r? @thomcc

(rust-highfive has picked a reviewer for you, use r? to override)

[thomcc]

Impl looks fine but this needs libs-api FCP.

[lopopolo]

Impl looks fine but this needs libs-api FCP.

oh whoops, it looks like I missed the magic comment rustbot asked me to make. Thanks @thomcc!

[yaahc]

Looks good to me, @lopopolo could you also make a stabilization report¹? Once we've got that I'll go ahead and kick off an FCP.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html#stabilization-report ↩

[lopopolo]

Stabilization Report

This stabilization report is for a partial stabilization of the bound_as_ref feature. Tracking issue: #80996.

Implementation History

• Bound::as_ref and Bound::as_mut were added in Add as_ref and as_mut methods for Bound #80444 in the Rust 1.51.0 timeframe.
• These functions have remained unchanged since they were introduced in Add as_ref and as_mut methods for Bound #80444.
• Bound::as_ref and Bound::as_mut were proposed for stabilization approximately 6 months after being on nightly: Tracking Issue for bound_as_ref #80996 (comment).
• Members of the API team expressed concerns that Bound::as_mut was lacking a motivating use case.
• A poll for the API team to resolve questions around Bound::as_mut was initiated on June 28, 2021: Tracking Issue for bound_as_ref #80996 (comment). The poll was not finalized.
• On July 22, 2022 @lopopolo proposed partially stabilizing the uncontroversial Bound::as_ref portion of the bound_as_ref feature: Tracking Issue for bound_as_ref #80996 (comment).

API Summary

This stabilization report proposes the following API to be stabilized:

impl<T> Bound<T> {
    pub fn as_ref(&self) -> Bound<&T>;
}

This new API has a motivating usecase to assist in the implementation of the RangeBounds<T> trait for custom range-like data types that store Bound internally.

Experience Report

Code such as this is ready to be converted to this API:

https://github.com/artichoke/artichoke/blob/0a19084bd1c7a8bd65e10e6b1ff99aedeec784ee/artichoke-backend/src/extn/core/matchdata/mod.rs#L54-L74

@dtolnay has remarked that Bound::as_ref is well-motivated given that RangeBounds<T> revolves around returning Bound<&T>: #80996 (comment).

[yaahc]

thank you very much @lopopolo!

@rfcbot merge

[rfcbot]

Team member @yaahc has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @yaahc

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[lopopolo]

@yaahc did I do something wrong that has caused this proposed FCP to hang open? Do I need to update the since attribute since 1.63.0 has gone out?

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[est31]

👋 Hello, I'm writing this comment in this stabilization PR to notify you, the authors of this PR, that #100591 has been merged, which implemented a change in how features are stabilized.

Your PR has been filed before the change, so will likely require modifications in order to comply with the new rules. I recommend you to:

1. rebase the PR onto latest master, so that uses of the placeholder are possible.
2. replace the version numbers in the PR with the placeholder CURRENT_RUSTC_VERSION. For language changes, this means the version numbers in accepted.rs (example: 4caedba). For library changes, this means the since fields (example e576a9b).

That's it! The CURRENT_RUSTC_VERSION placeholder will, as part of the release process, be replaced with the version number that the PR merged for. It can be used anywhere in rust-lang/rust, not just accepted.rs and the since fields.

If you have any questions, feel free to drop by the zulip stream, or ping me directly in this PR's thread. Thanks! 👋

[lopopolo]

@est31 I think I got this sorted out. Thanks for making this change! It directly addresses my concern from #99736 (comment).

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[lopopolo]

@yaahc @joshtriplett can this be merged now that the FCP is concluded?

[dtolnay]

@bors r+

[bors]

📌 Commit 773df67 has been approved by dtolnay

It is now in the queue for this repository.