Rationale

The IEEE 754:2008 and IEEE 754:2019 spec define a number of operations (some required, some recommended, and some optional) and the .NET Framework exposes a good number, but not all of them.

It would be ideal to ensure that all required operations are properly exposed and that they are compliant with the IEEE spec. Where a recommended or optional operation is also exposed, we should ensure that it is also compliant. Where a behavior/operation/feature is explicitly not implemented, we should ensure that it is properly documented with any reasoning as to why it is not supported.

For the purposes of this proposal, this document only covers the binary operations. The IEEE spec also defines a format and set of operations for decimal values, but those are not supported by .NET in any form today and should be covered separately.

Additionally, this general proposal is meant to track the overall status, and sub-proposals, where applicable should be opened to cover specific behaviors/operations. This proposal does not go in detail as to any special behaviors or handling of individual operations, which should be checked and validated separately.

Encodings

Support for all formats and representations is language/implementation-defined. .NET currently supports binary32 and binary64. There have also been requests for binary16, binary128, and arbitrarily sized binary{k}.

The basic encodings defined are:

• binary32 - System.Single
• binary64 - System.Double
• binary128

The extended encodings defined are:

• binary16 - Proposed as System.Half
• binary{k}, Where k >= 128 and is a multiple of 32

Attributes

Several attributes that control the semantics of a "block" are given. For any exposed attribute, you must provide a means of statically setting the default and each support value. Providing a means to dynamically set the attributes is recommended.

Required

• Rounding Direction
  • Required: roundTiesToEven - Default, System.MidpointRounding.ToEven
  • Optional: roundTiesToAway - System.MidpointRounding.AwayFromZero
  • Required: roundTowardPositive - Not Supported
  • Required: roundTowardNegative - Not Supported
  • Required: roundTowardZero - Not Supported

Recommended

• Alternate Exception Handling - Not Supported (currently out of scope)

Optional

• Preferred Width - Not Supported
• Value Changing Optimizations - Not Supported
• Reproducibility - Not Supported

If setting the attributes dynamically is supported, the following are required

• binaryRoundingDirection getBinaryRoundingDirection() - Not Supported
• void setBinaryRoundingDirection(binaryRoundingDirection) - Not Supported
• modeGroup saveModes() - Not Supported
• void restoreModes(modeGroup) - Not Supported
• void defaultModes() - Not Supported

Required Operations

All operations listed below are considered required

General (T is a floating-point format)

• T roundToIntegralTiesToEven(T) - Math.Round, Math.Round w/ MidpointRounding.ToEven
• T roundToIntegralTiesToAway(T) - Math.Round w/ MidpointRounding.AwayFromZero
• T roundToIntegralTowardZero(T) - Math.Round w/ MidpointRounding.ToZero
• T roundToIntegralTowardPositive(T) - Math.Round w/ MidpointRounding.ToPositiveInfinity
• T roundToIntegralTowardNegative(T) - Math.Round w/ MidpointRounding.ToNegativeInfinity
• T roundToIntegralExact(T) - Not supported, meant to use the current Rounding Direction attribute
• T nextUp(T) - Math.BitIncrement
• T nextDown(T) - Math.BitDecrement
• T remainder(T, T) - Math.IEEERemainder

logBFormat operations (T is a floating-point format, U can be an integral format or the same type as T)

• T scaleB(T, U) - Math.ScaleB
• U logB(T) - Math.LogB

Arithmetic

• T addition(T x, T y) - x + y
• T subtraction(T x, T y) - x - y
• T multiplication(T x, T y) - x * y
• T division(T x, T y) - x / y
• T squareRoot(T) - Math.Sqrt
• T fusedMultiplyAdd(T, T, T) - Math.FusedMultiplyAdd
• T convertFromInt(integerFormat x) - (T)x
• integerFormat convertToIntegerTiesToEven(T) - Not Supported
• integerFormat convertToIntegerTowardZero(T x) - (integerFormat)x, Not supported as an explicit operation
• integerFormat convertToIntegerTowardPositive(T) - Not Supported
• integerFormat convertToIntegerTowardNegative(T) - Not Supported
• integerFormat convertToIntegerTiesToAway(T) - Not Supported
• integerFormat convertToIntegerExactTiesToEven(T) - Not supported, Requires floating-point exception handling
• integerFormat convertToIntegerExactTowardZero(T) - Not Supported, Requires floating-point exception handling
• integerFormat convertToIntegerExactTowardPositive(T) - Not Supported, Requires floating-point exception handling
• integerFormat convertToIntegerExactTowardNegative(T) - Not Supported, Requires floating-point exception handling
• integerFormat convertToIntegerExactTiesToAway(T) - Not Supported, Requires floating-point exception handling

Conversion

• U convertFormat(T x) - (U)x where U is another floating-point format
• T convertFromDecimalCharacter(decimalCharacterSequence) - Double.Parse
• decimalCharacterSequence convertToDecimalCharacter(T, conversionSpecification) - Double.ToString, Double.ToString w/ format
• T convertFromHexCharacter(hexCharacterSequence) - Not Supported
• hexCharacterSequence convertToHexCharacter(T, conversionSpecification) - Not Supported

Sign Bit

• T copy(T x) - var y = x
• T negate(T x) - -x
• T abs(T) - Math.Abs
• T copySign(T, T) - Math.CopySign

Comparison

• boolean compareQuietEqual(T x, T y) - x == y
• boolean compareQuietNotEqual(T x, T y) - x != y
• boolean compareSignalingEqual(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareSignalingGreater(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareSignalingGreaterEqual(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareSignalingLess(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareSignalingLessEqual(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareSignalingNotEqual(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareSignalingNotGreater(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareSignalingLessUnordered(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareSignalingNotLess(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareSignalingGreaterUnordered(T x, T y) - Not Supported, Requires floating-point exception handling
• boolean compareQuietGreater(T x, T y) - x > y
• boolean compareQuietGreaterEqual(T x, T y) - x >= y
• boolean compareQuietLess(T x, T y) - x < y
• boolean compareQuietLessEqual(T x, T y) - x <= y
• boolean compareQuietUnordered(T x, T y) - Not Supported
• boolean compareQuietNotGreater(T x, T y) - Not Supported
• boolean compareQuietLessUnordered(T x, T y) - Not Supported
• boolean compareQuietNotLess(T x, T y) - Not Supported
• boolean compareQuietGreaterUnordered(T x, T y) - Not Supported
• boolean compareQuietOrdered(T x, T y) - Not Supported

Conformance

• boolean is754version1985() - Not Supported
• boolean is754version2008() - Not Supported
• boolean is754version2019() - Not Supported

General

• enum class(T) - Not Supported
  • signalingNaN
  • quietNaN
  • negativeInfinity
  • negativeNormal
  • negativeSubnormal
  • negativeZero
  • positiveZero
  • positiveSubmormal
  • positiveNormal
  • positiveInfinity
• boolean isSignMinus(T) - Double.IsNegative
• boolean isNormal(T) - Double.IsNormal
• boolean isFinite(T) - Double.IsFinite
• boolean isZero(T) - INumberBase.IsZero, but not directly exposed
• boolean isSubnormal(T) - Double.IsSubnormal
• boolean isInfinite(T) - Double.IsInfinity
• boolean isNaN(T) - Double.IsNaN
• boolean isSignaling(T) - Not Supported
• boolean isCanonical(T) - INumberBase.IsCanonical, but not directly exposed
• enum radix(T) - INumberBase.Radix, but not directly exposed
  • 2 for binary
• boolean totalOrder(T, T) - Not Supported
• boolean totalOrderMag(T, T) - Not Supported

Flags

• void lowerFlags(exceptionGroup) - Not Supported
• void raiseFlags(exceptionGroup) - Not Supported
• boolean testFlags(exceptionGroup) - Not Supported
• boolean testSavedFlags(flags, exceptionGroup) - Not Supported
• void restoreFlags(flags, exceptionGroup) - Not Supported
• flags saveAllFlags() - Not Supported

Exceptions

Exceptions are not currently supported by the CoreCLR and no mechanism to control them is currently made available. I have considerd them "out of scope" for the purposes of this document.

Recommended Operations

Additional Mathematical Operations

• T exp(T) - Double.Exp
• T expm1(T) - Double.ExpM1
• T exp2(T) - Double.Exp2
• T exp2m1(T) - Double.Exp2M1
• T exp10(T)- Double.Exp10
• T exp10m1(T)- Double.Exp10M1
• log - Math.Log
• log2 - Math.Log2
• log10 - Math.Log10
• T logp1(T) - Double.LogP1
• T log2p1(T) - Double.Log2P1
• T log10p1(T) - Double.Log10P1
• T hypot(T, T) - Double.Hypot
• T rSqrt(T) - Not Supported
• T compound(T, T) - Approved, not implemented yet
• T rootn(T, T) - Double.RootN
• T pown(T, T) - Not Supported
• T pow(T, T) - Math.Pow
• T powr(T, T) - Not Supported
• T sin(T) - Math.Sin
• T cos(T) - Math.Cos
• T tan(T) - Math.Tan
• T sinPi(T) - Double.SinPi
• T cosPi(T) - Double.CosPi
• T tanPi(T) - Double.TanPi
• T asin(T) - Math.Asin
• T acos(T) - Math.Acos
• T atan(T) - Math.Atan
• T atan2(T, T) - Math.Atan2
• T asinPi(T) - Double.ASinPi
• T acosPi(T) - Double.ACosPi
• T atanPi(T) - Double.ATanPi
• T atan2Pi(T, T) - Double,ATan2Pi
• T sinh(T) - Math.Sinh
• T cosh(T) - Math.Cosh
• T tanh(T) - Math.Tanh
• T asinh(T) - Math.Asinh
• T acosh(T) - Math.Acosh
• T atanh(T) - Math.Atanh

Reduction

• T sum(T[]) - Not Supported
• T dot(T[], T[]) - Not Supported
• T sumSquare(T[]) - Not Supported
• T sumAbs(T[]) - Not Supported
• T[] scaledProd(T[]) - Not Supported
• T[] scaledProdSum(T[], T[]) - Not Supported
• T[] scaledProdDiff(T[], T[]) - Not Supported

Augmented Arithmetic

• (T, T) augmentedAddition(T, T)
• (T, T) augmentedSubtraction(T, T)
• (T, T) augmentedMultiplication(T, T)

Minimum and Maximum

• T minimum(T, T) - Math.Min
• T minimumNumber(T, T) - Double.MinNumber
• T maximum(T, T) - Math.Max
• T maximumNumber(T, T) - Double.MaxNumber
• T minimumMagnitude(T x, T y) - Math.MinMagnitude
• T minimumMagnitudeNumber(T x, T y) - Double.MinMagnitudeNumber
• T maximumMagnitude(T x, T y) - Math.MaxMagnitude
• T maximumMagnitudeNumber(T x, T y) - Double.MaxMagnitudeNumber

NaN

• T getPayload(T) - Not Supported
• T setPayload(T) - Not Supported
• T setPayloadSignaling(T) - Not Supported