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.
These are used only in TestSupport, but it's still nice to get them right. Signed types had a long-standing bug in how overflow was computed for multiplication, and masking shifts would do the wrong thing when the bitwdith was not a power of two and the shift count was negative. I also added implementations of &*, &+, and &-.
Improved how tolerance is applied close to infinity for complex division
(this still could use a more principled approach, but at least we're in
the right ballpark now). Tightened up the tolerance for semi-exhaustive
testing too, since that can be done now.
This commit adds the following to the RealFunctions protocol:
static func _relaxedAdd(_:Self, _:Self) -> Self
static func _relaxedMul(_:Self, _:Self) -> Self
These are equivalent to + and *, but have "relaxed semantics"; specifically, they license the compiler to reassociate them and to form FMA nodes, which are both significant optimizations that can easily make many common loops 8-10x faster. These transformation perturb results slightly, so they should not be enabled without care, but the results with the relaxed operations are--for most purposes--"just as good as" (and often better than) what strict operations produce. The main thing to beware of is that they are no longer portable; different compiler versions and different targets and optimization flags will result in different results.
They are underscored because they are not stable API. In particular:
- `RealFunctions` is not really the right protocol for these (and neither is `Real`). I need to do some thinking about where to attach them.
- Even if it were the right protocol, these are more like implementation hooks than the API I really want people to use (TBD).
- I like "relaxed" more than other commonly used idioms ("fast"), but I'm not sure it's the name I ultimately want.
The conformance was breaking CI testing, because the CI bots use a macOS version that predates availability of the _Differentiation module, and the compiler-generated differentation operations have neither availability attributes nor checks, so any reference to those operations simply crashes in dyld because the library is not present. We can add availability, but that's not really accurate either, because these operations are not actually binary-stable, so while we wouldn't crash in dyld, we also might not work correctly in the future. We could mark them unavailable on Apple platforms, but that's also not quite right (and further means that they're not going to get a lot of attention). The best solution seems to be to remove the conformance (which was never source-stable).