6.3.4 Signals

##
6.3.4 Signals

Signals represent conditions that arise during computation. Each corresponds to one context flag and one context trap enabler.

The context flag is incremented whenever the condition is encountered. After the computation, flags may be checked for informational purposes (for instance, to determine whether a computation was exact). After checking the flags, be sure to clear all flags before starting the next computation.

If the context's trap enabler is set for the signal, then the condition causes a Python exception to be raised. For example, if the `DivisionByZero` trap is set, then a `DivisionByZero` exception is raised upon encountering the condition.

class `Clamped`
  Altered an exponent to fit representation constraints.

  Typically, clamping occurs when an exponent falls outside the context's `Emin` and `Emax` limits. If possible, the exponent is reduced to fit by adding zeroes to the coefficient.

class `DecimalException`
  Base class for other signals and a subclass of `ArithmeticError`.

class `DivisionByZero`
  Signals the division of a non-infinite number by zero.

  Can occur with division, modulo division, or when raising a number to a negative power. If this signal is not trapped, returns `Infinity` or `-Infinity` with the sign determined by the inputs to the calculation.

class `Inexact`
  Indicates that rounding occurred and the result is not exact.

  Signals when non-zero digits were discarded during rounding. The rounded result is returned. The signal flag or trap is used to detect when results are inexact.

class `InvalidOperation`
  An invalid operation was performed.

  Indicates that an operation was requested that does not make sense. If not trapped, returns `NaN`. Possible causes include:

              Infinity - Infinity
              0 * Infinity
              Infinity / Infinity
              x % 0
              Infinity % x
              x._rescale( non-integer )
              sqrt(-x) and x > 0
              0 ** 0
              x ** (non-integer)
              x ** Infinity

class `Overflow`
  Numerical overflow.

  Indicates the exponent is larger than `Emax` after rounding has occurred. If not trapped, the result depends on the rounding mode, either pulling inward to the largest representable finite number or rounding outward to `Infinity`. In either case, `Inexact` and `Rounded` are also signaled.

class `Rounded`
  Rounding occurred though possibly no information was lost.

  Signaled whenever rounding discards digits; even if those digits are zero (such as rounding `5.00` to `5.0`). If not trapped, returns the result unchanged. This signal is used to detect loss of significant digits.

class `Subnormal`
  Exponent was lower than `Emin` prior to rounding.

  Occurs when an operation result is subnormal (the exponent is too small). If not trapped, returns the result unchanged.

class `Underflow`
  Numerical underflow with result rounded to zero.

  Occurs when a subnormal result is pushed to zero by rounding. `Inexact` and `Subnormal` are also signaled.

The following table summarizes the hierarchy of signals:

        exceptions.ArithmeticError(exceptions.StandardError)
            DecimalException
                Clamped
                DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
                Inexact
                    Overflow(Inexact, Rounded)
                    Underflow(Inexact, Rounded, Subnormal)
                InvalidOperation
                Rounded
                Subnormal