Stabilize funnel_shifts (including const)

[tgross35]

funnel_shl and funnel_shr have been around for close to a year, the unchecked versions for a number of months. These are reasonably small and uncontroversial, and it can be tricky to get similar performance with a fallback; stabilize them here.

Newly stable API:

impl {u8, u16, u32, u64, u128, usize} {
    pub const fn funnel_shl(self, right: Self, shift: u32) -> Self;
    pub const fn funnel_shr(self, right: Self, shift: u32) -> Self;

    pub const unsafe fn unchecked_funnel_shl(self, right: Self, shift: u32) -> Self;
    pub const unsafe fn unchecked_funnel_shr(self, right: Self, shift: u32) -> Self;
}

The tracking issue also mentions a wrapping_ version but it has not been implemented.

Closes: #145686 (tracking issue, wrapping versions will need a new issue)

This involves an intrinsic stabilization so needs FCP from both @rust-lang/lang and @rust-lang/libs-api.

@rustbot label +I-lang-nominated +I-libs-api-nominated

Cc others who have been involved: @RalfJung, @folkertdev, @sayantn

r? libs

[rustbot]

Some changes occurred to the intrinsics. Make sure the CTFE / Miri interpreter
gets adapted for the changes, if necessary.

cc @rust-lang/miri, @RalfJung, @oli-obk, @lcnr

⚠️ #[rustc_allow_const_fn_unstable] needs careful audit to avoid accidentally exposing unstable
implementation details on stable.

cc @rust-lang/wg-const-eval

⚠️ #[rustc_intrinsic_const_stable_indirect] controls whether intrinsics can be exposed to stable const
code; adding it needs t-lang approval.

cc @rust-lang/wg-const-eval

miri is developed in its own repository. If the Miri part of this change can be broken out, consider making this change to rust-lang/miri instead. However, if Miri needs adjusting for rustc changes, just ignore this message.

cc @rust-lang/miri

stdarch is developed in its own repository. If possible, consider making this change to rust-lang/stdarch instead.

cc @Amanieu, @folkertdev, @sayantn

[tgross35]

Note that const_trait_impl is only needed for the fallback. We could implement a version without it if needed.

The fallback traits are gated behind core_intrinsics_fallbacks, I'm not sure whether there's a cleaner way to do this.

View changes since the review

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[jdahlstrom]

This should be "right half", right?

[tgross35]

You're right; #161065

[traviscross]

Thanks @tgross35.

@rfcbot fcp merge lang,libs

[rust-rfcbot]

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

• @Amanieu
• @cuviper
• @joshtriplett
• @nikomatsakis
• @scottmcm
• @the8472
• @thomcc
• @tmandry
• @traviscross

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!

cc @rust-lang/lang-advisors: FCP proposed for lang, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.

[scottmcm]

Zero lang concerns; this is a value operation with fallback MIR showing it can be implemented with existing rust.

@rfcbot reviewed

[scottmcm]

A concern for the libs(-api) part: Is this actually guaranteed to panic for out-of-range shifts?

It feels inconsistent with other things. I'd expect that funnel_shift would wrap in release and panic in debug, and that there'd be a strict_funnel_shift that would always panic for out-of-range shifts.

---

And it's a bit weird to not have the wrapping version of this. It'd be trivial to implement -- just mask the shift passed to unchecked -- so why not just add it before stabilizing the set?

[tgross35]

Wrapping by default was the original proposal but was decided against, see rust-lang/libs-team#642 (comment).

The wrapping_ version was accepted as part of that ACP, but it never got added. I don't think we'd want to stabilize it right away but also don't want it to block these any longer since they're ready and useful.

[pthariensflame]

We’ll implement the wrapping versions, independently of this PR.