It's a useful operation, but it deserves its own API to allow the use of a custom random source.
Also, the existing API blocks some constant-folding operations because the call to the system random source is an opaque optimization barrier, so removing it allows us to produce better codegen for the other rounding modes.
We're also bumping required Swift version to 5.9, and removing the executable test targets for log/log1p, as they're really only useful for development of those algorithms.
IntegerUtilities has RoundingRule that is a superset of FloatingPointRoundingRule; many of these are also useful when working with floating-point. This change provides a `rounding(_:)` function similar to the standard libraries `rounded(_:)` that makes all of them available. It has a different name instead of being a shadow because otherwise existing use sites like `rounded(.down)` would become ambiguous.
These were omitted in the first pass over integer rounding rules, but are generally useful and make good sense to have available. In particular, toNearestOrUp is the natural mode for a lot of fixed-point arithmetic, and frequently has HW support on SIMD units, so it makes good sense to have a name for that. Once you add that, having nearestOrDown also makes sense, and then nearestOrZero should exist by analogy to nearestOrAway. Also beefed up testing and refactored the division rounding code somewhat.
The standard-library documentation for `trailingZeroBitCount` states:
> If the value is zero, then `trailingZeroBitCount` is equal to `bitWidth`.
Thus, if `T` is not a fixed-width integer type, and `x == 0`, and `y` has more trailing zeros than the representation of `x`, then the gcd calculation will be incorrect.
In particular, the left-shift by `min(xtz, ytz) == xtz` will not “undo” the earlier right-shift by `ytz`, so the final result will be incorrectly right-shifted by `ytz - xtz`.
To fix this I have added an early exit when `x == 0`. I am not sure if this is the optimal solution, and I’m open to alternatives.
***
This change ensures that `x != 0` at the top of the loop, so I have also converted it from a `while` to a `repeat-while` loop, in order to eliminate a redundant extra comparison on the first iteration.
I don’t know if this actually affects performance, and I’m happy to change it back if that’s preferred.
Also implemented some basic statistical tests for .stochastic and reorganized code a little bit. The statistical justification of the thresholds for these tests should be explained a bit more, and we should decide on a policy in general for statistical tests that may fail sporadically, but these shouldn't be very noisy for now.
Fairly correct implementation of right-shift with rounding. Also fairly efficient, though I'm sure I'll find some cases where we're generating uncessary overflow checks upon further inspection. Nonetheless, a decent enough start.
Seeded with rotate(right:) and rotate(left:) on FixedWidthInteger. These implementations are basically sane, but need documentation written for users who are not already familiar with bitwise rotation.