[SR-14384][SR-14974] Fix Decimal.ulp, nextUp, nextDown

[xwu]

This PR is a follow-up to #3014, addressing the first issue outlined there and correspondingly addressing SR-14384 regarding nextDown and nextUp. Namely:

• The implementation of ulp does not currently actually return the "unit in the last place" as an IEEE floating-point type would, which should reflect the spacing between two consecutive representable numbers. Instead, the result currently reflects the idiosyncratic internal representation of Decimal values, with the consequence that the "unit in the last place" of 1 is allegedly 1.
• Relatedly, nextUp is documented to give "the least representable value that is greater than this decimal," but (1 as Decimal).nextUp is allegedly 2. (Similarly for nextDown.)

This behavior is discordant with that of binary floating-point types as well as the documentation. This PR addresses both of these issues by returning the true spacing between two consecutive representable numbers as the ulp [for most values], and adjusting the implementations of both nextUp and nextDown to rely on ulp [for most values]. Both the overlay and the swift-corelibs implementations are changed, and appropriate tests are added.

[xwu]

@swift-ci test Linux

[xwu]

@swift-ci test Linux

[xwu]

@swift-ci test macOS

[xwu]

@swift-ci test

[spevans]

All ok, just requires some changes in the tests.

[xwu]

Will revise later this week or over the weekend. There’s a subtle bug owing to the fact that the max supported significand of this type is not 10 ** 38 - 1 but rather 2 ** 128 - 1.

[spevans]

@swift-ci test

[xwu]

Thanks :) It’s not quite done, and I’ll keep plugging away at it.

[xwu]

This logic is the Decimal counterpart to https://github.com/apple/swift/blob/4c923d6dda6453d3af635f0ac1d64935a21673bb/stdlib/public/core/FloatingPointTypes.swift.gyb#L946 (without the parts dealing with negative zero and infinity).

[xwu]

@swift-ci test

[xwu]

@spevans This should be ready now.

[millenomi]

@phausler Would you mind putting a checkmark here if it looks right?

[phausler]

There is a question of syncing this but overall the changes look accurate. ulp and such were never fully defined so this seems plausible to bring em in line w/ the expectations.

[xwu]

@phausler By syncing you mean the overlay? It’s still being built from the overlay files in this repo, yes?

[phausler]

I am talking about the actual overlay in the system, this is only the open source version of it; the commentary was more of a point of book-keeping for the Foundation team