Tracking Issue for checked bitshifts

Feature gate: #![feature(exact_bitshifts)]

This is a tracking issue for checked bitshifts, i.e. bitshifts that can be losslessly reversed.
ACP: rust-lang/libs-team#570

Public API

impl iX/uX {
    // Shift succeeds if `shift < Self::BITS` and right shifting the result returns the original value.
    fn exact_shl(self, shift: u32) -> Option<Self>;
    unsafe fn unchecked_exact_shl(self, shift: u32) -> Self;

    // Shift succeeds if `shift < Self::BITS` and left shifting the result returns the original value.
    fn exact_shr(self, shift: u32) -> Option<Self>;
    unsafe fn unchecked_exact_shr(self, shift: u32) -> Self;
}

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

Implementation: add exact bitshifts #144342
Add new intrinsics rather than building on unchecked_sh{l,r} actually checked bitshifts libs-team#570 (comment)
Final comment period (FCP)¹
Stabilization PR

Unresolved Questions

Should exact_shl panic instead of return None, then introduce a new checked_exact_shl -> Option? add exact bitshifts #144342 (comment)
None yet.

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

@lolbinarycat

@lolbinarycat Are you still interested in implementing this? If not, please let me know so I know it's available. Regardless, rust-lang/libs-team#570 can be closed now.

@Qelxiros

@Qelxiros I'd get around to it eventually, but I've got a fairly long backlog, so if anyone wants to claim this issue, they're free to, just cc me on the implementation PR so I can take a look.

@rustbot

@rustbot label -S-tracking-unimplemented

~~Is there much of a usecase for the unchecked_ versions of these? The backend is getting the same information as for unchecked_sh{l,r}, only the preconditions differ slightly.~~ yes it can have this information, see rust-lang/libs-team#570 (comment). The initial PR just didn't have new intrinsics.

Rollup merge of rust-lang#144342 - Qelxiros:exact-bitshifts, r=tgross35

Unrolled build for #144342

Rollup merge of rust-lang#144342 - Qelxiros:exact-bitshifts, r=tgross35

We discussed this in the @rust-lang/libs-api meeting today. We would like any API decided here to be consistent with the API for exact division (#139911) which we also discussed.

We found 4 behaviors that users might be desirable:

Signature	Shift out of range	Non-exact shift result
`fn checked_exact_shl(self, rhs: Self) -> Option<Self>`	`None`	`None`
`fn strict_exact_shl(self, rhs: Self) -> Self`	Panic	Panic
`fn exact_shl(self, rhs: Self) -> Option<Self>`	Panic on debug, wrap on release (matches `shl`)	`None`
`unsafe fn unchecked_exact_{shl,shr}(self, rhs: Self) -> Self`	UB	UB

(same with exact_shr)

The reasoning behind these choices is that an out-of-range shift is likely to be a bug, while an inexact result is likely something that a user might want to check for.

We are confident that we would like to stabilize unchecked_exact_{shl,shr} as described here, but are less sure about the other ones. Are those something that you would see yourself using in practice?

Rollup merge of rust-lang#147771 - nxsaken:div_shlr_exact, r=dtolnay

Unrolled build for #147771

Rollup merge of #147771 - nxsaken:div_shlr_exact, r=dtolnay

Rollup merge of rust-lang#147771 - nxsaken:div_shlr_exact, r=dtolnay

I think it would make sense to implement these on NonZero as well since x.exact_sh*(y) will never be zero if x is not zero.

The reasoning behind these choices is that an out-of-range shift is likely to be a bug, while an inexact result is likely something that a user might want to check for.

I partially disagree with this because code like this will have UB when x is zero even though it shouldn't. When the shift is out-of-range and it's not being applied to zero, its probably a bug though.

fn left_align(x: u32) -> u32 {
     let ctlz = x.leading_zeros();
     // SAFETY: leading zeros gives the maximum safe shift, unless
     // `x` is 0 where there is no maximum and it is always safe.
     unsafe { x.unchecked_exact_shl(ctlz) }
}

I also have other code in a project of mine that I would like to be able to use unchecked_exact_shr on to remove factors of 2 while telling the compile the value won't become zero if it wasn't already but I wouldn't be able to if this goes through.
Alternatively, a version of leading_zeros or trailing_zeros that returns 0 (or some other value less than the type's bitcount) when the input is zero would partially solve this problem. BITS-1 might make more sense so that x.trailing_zeros().min(y.trailing_zeros()) is still accurate for gcd functions and similar which are one of the main places I run into this.

Add contracts for unchecked_{shl,shr}_exact

Navigation Menu

Repository navigation

Tracking Issue for checked bitshifts #144336

Public API

Steps / History

Unresolved Questions

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tracking Issue for checked bitshifts #144336

Description

Public API

Steps / History

Unresolved Questions

Footnotes

Activity

Qelxiros commented on Jul 23, 2025

lolbinarycat commented on Jul 23, 2025

Qelxiros commented on Jul 24, 2025

tgross35 commented on Sep 3, 2025

Amanieu commented on Oct 15, 2025

Apersoma commented on Apr 24, 2026

Apersoma commented on Apr 24, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions