Questionable `operator<<` error handling and missing documentation

[eisenwave]

int128/include/boost/int128/detail/int128_imp.hpp

Lines 1349 to 1357 in f905e22

	BOOST_INT128_HOST_DEVICE constexpr int128_t operator<<(const int128_t lhs, const int128_t rhs) noexcept
	{
	if (rhs.high != 0 || rhs.low >= 128)
	{
	return 0;
	}
	return lhs << rhs.low;
	}

Some issues with this:

1. The behavior is to simply treat the error cases (overly large shifts and negative shifts) as resulting in zero, but it's not obvious this would happen. Mathematically, << s means $\times 2^s$, and the rest of the library treats overflow as wrapping. Why would a large shift then neither wrap the shift amount (via bitwise AND) nor wrap the resulting product of the multiplication? It just gives you zero on large shifts, which is what std::shl/Rust u32::unbounded_shl does. However, it's also not consistent about matching std::shl because negative shifts result in zero.

2. It's not clear from the documentation that overly large shifts and negative shifts are considered undefined behavior or are guaranteed to yield zero.

[mborland]

I'll double check what __int128 does in this case.

[eisenwave]

I think even if you consider it to be UB (which should match all the builtin types), it would be easier and presumably faster to implement it as a one-liner like

return lhs << (rhs.low & 0x7f);

This would match u32::wrapping_shl and it would be branchless.

And even if you don't do any that, the if statement deserves an [[unlikely]].