Add inherent unchecked_shl, unchecked_shr to integers

[clarfonthey]

Tracking issue: #85122.

Adding more of these methods, since these are missing.

[rust-highfive]

r? @scottmcm

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

[scottmcm]

Thanks for the PR, @clarfonthey!

The shift semantics for Rust are a bit weird, though. Do you know any situations where the masking the shift amount is a problem in practice?

I feel like someone reaching for these would often actually want things like shl n[us]w or [la]shr exact, rather than what these intrinsics actually do.

But at the same time I guess we're stuck with checked_shl looking only at the shift amount, so maybe this is the only reasonable behaviour? And then shl_nowrap and shr_exact would go with div_exact in the "well there's another category of these methods that needs a different naming pattern"?

Any thoughts on whether these should be added, @rust-lang/libs ?

[scottmcm]

I thought about this some more, and came around to the idea that it's probably fine to have these in nightly because of the parallel with checked_sh[lr]. I'll let libs make the harder decision about stabilization later.

So @clarfonthey can you please:

• Update the documentation to explicitly mention that this is not about overflow in output values. (Not that the docs hint that it could be, but for unsafe methods I'd rather be extra clear.)
• Since they're unsafe, add a # Safety section (example) with a bullet for each condition that must be uphelp to avoid being UB. (You have it in the doc comment already, but to make it easier on the person wanting to write a // SAFETY justification on their unsafe block, I like seeing it put under a very explicit header.)

[clarfonthey]

Will update the docs for the methods in a bit. Also will add the # Safety notice to the other unsafe methods as they do not include it either, and I just copied their docs.

In terms of the actual behaviour, even though we're technically tabling the discussion: I strongly believe that we should keep the existing behaviour, as it matches the overflow behaviour of the operators normally. I definitely think we could add new methods in the future for what you specified, though. For example, division can always allow a nonzero remainder, checked or not, but longer-term we can add a new method to use exact_div for when the remainder is guaranteed to be zero.

Mostly just my thoughts on that.

[CraftSpider]

Wording nit, not super important as you're already updating the docs, but noticed as I was reading.

[clarfonthey]

Wording nit, not super important as you're already updating the docs, but noticed as I was reading.

Apologies, I just was about to push my changes that fixed that when you commented. :P

I chose to use "larger than" instead of "greater than" since that's the wording that the existing checked methods use.

[clarfonthey]

@rustbot label -S-waiting-on-author +S-waiting-on-review

[scottmcm]

Thanks for the updates, @clarfonthey! I've updated the tracking issue with some extra things to ponder before stabilization.

@bors r+

[bors]

📌 Commit 2a40f24 has been approved by scottmcm

[bors]

⌛ Testing commit 2a40f24 with merge 6166929...

[bors]

☀️ Test successful - checks-actions
Approved by: scottmcm
Pushing 6166929 to master...