Wrapping shift confusion

[andrewwhitehead]

Currently, num_traits::WrappingShl and WrappingShr are implemented for numeric types. So are the ShlVartime/ShrVartime traits which also have corresponding wrapping shift methods (but vartime).

The method description in num_traits matches the one for u32::wrapping_shl and related standard-library methods, which "masks off" the high bits of the shift. This means that N.wrapping_shl(N::BITS) == N.wrapping_shl(0) == N. This does not correspond with the behaviour in the library, which returns N::ZERO when the shift exceeds the maximum size (for types other than Limb). The standard library calls this unbounded_shl/unbounded_shr (new as of Rust 1.87).

[tarcieri]

Should we adopt core conventions for clarity?

[andrewwhitehead]

There's also some ambiguity over what Wrapping(N).shr/shl should do. The standard library wrapping shift, or unbounded shift?

[andrewwhitehead]

I think the wrapping operations should behave like core. Some methods like UintRef::wrapping_shl_assign could be named unbounded_shl_assign to correspond with the core naming. I'm a bit worried about the breaking change though, for people using the wrapping shift operations.

[tarcieri]

It seems like we should rename the existing implementation to unbounded_*, implement one with core's semantics, and then change Wrapping to use the new implementation that follows core semantics

[andrewwhitehead]

There doesn't seem to be num-traits equivalents of the unbounded shifts, although there are CheckedShl and CheckedShr which aren't implemented currently. Might need new UnboundedShl and UnboundedShr traits as well?

[tarcieri]

That seems fine, we can add them here for now. Perhaps we should also propose them upstream?