FloatingPointControl

Control the Floating point hardware

Change the IEEE754 floating-point rounding mode and the floating-point hardware exceptions.

By default, the rounding mode is roundToNearest and all hardware exceptions are disabled. For most applications, debugging is easier if the division by zero, overflow, and invalid operation exceptions are enabled. These three are combined into a severeExceptions value for convenience. Note in particular that if invalidException is enabled, a hardware trap will be generated whenever an uninitialized floating-point variable is used.

All changes are temporary. The previous state is restored at the end of the scope.

version(FloatingPointControlSupport)

struct FloatingPointControl {

RoundingMode rounding [@property setter];

static RoundingMode rounding [@property getter];

static bool hasExceptionTraps [@property getter];

void enableExceptions(ExceptionMask exceptions);

void disableExceptions(ExceptionMask exceptions);

static ExceptionMask enabledExceptions [@property getter];

~this();

}

Destructor

~this ~this(): Clear all pending exceptions, then restore the original exception state and rounding mode.

Members

Functions

disableExceptions void disableExceptions(ExceptionMask exceptions): Disable (mask) specific hardware exceptions. Multiple exceptions may be ORed together.
enableExceptions void enableExceptions(ExceptionMask exceptions): Enable (unmask) specific hardware exceptions. Multiple exceptions may be ORed together.

Properties

enabledExceptions ExceptionMask enabledExceptions [@property getter]
hasExceptionTraps bool hasExceptionTraps [@property getter]
rounding RoundingMode rounding [@property setter]: Change the floating-point hardware rounding mode
rounding RoundingMode rounding [@property getter]

Examples

{
    FloatingPointControl fpctrl;

    // Enable hardware exceptions for division by zero, overflow to infinity,
    // invalid operations, and uninitialized floating-point variables.
    fpctrl.enableExceptions(FloatingPointControl.severeExceptions);

    // This will generate a hardware exception, if x is a
    // default-initialized floating point variable:
    real x; // Add `= 0` or even `= real.nan` to not throw the exception.
    real y = x * 3.0;

    // The exception is only thrown for default-uninitialized NaN-s.
    // NaN-s with other payload are valid:
    real z = y * real.nan; // ok

    // The set hardware exceptions and rounding modes will be disabled when
    // leaving this scope.
}

import std.math.rounding : lrint;

FloatingPointControl fpctrl;

fpctrl.rounding = FloatingPointControl.roundDown;
assert(lrint(1.5) == 1.0);

fpctrl.rounding = FloatingPointControl.roundUp;
assert(lrint(1.4) == 2.0);

fpctrl.rounding = FloatingPointControl.roundToNearest;
assert(lrint(1.5) == 2.0);