NumericEventHandler specifies or queries the event handling mechanism for one or more numeric events (see NumericEvent).  The six types of numeric events in Maple are:

The event handler settings are stored in the environment variable NumericEventHandlers, but should be set only by using the NumericEventHandler function. An event handler is always installed for each numeric event. The event handler is a user-supplied handler, the default handler, or the exception handler.

Because the vector of event handlers is stored in an environment variable, handlers installed during the execution of a procedure are automatically removed when the procedure exits.  This allows, for instance, an event handler to trigger an exception by installing the exception handler for the event, and then retriggering the event, without disturbing the higher-level settings for event handling.

When querying an event handler, NumericEventHandler returns either a procedure or one of the symbols default or exception.

If called with an equation or expression sequence of equations of the form event=action, NumericEventHandler installs the specified action (or actions) for the specified event (or events). It also returns an equation or expression sequence of equations displaying  the previously installed action (or actions) for the specified event (or events), which can be used as an argument to a subsequent call to NumericEventHandler to restore the previous state.

When setting an event handler, the handler can be specified as a procedure (either directly or by name); as the symbol default, which installs the default event handler for the specified event; or as the symbol exception, which installs the exception-raising event handler for the event.

If called with an event name or expression sequence of event names, NumericEventHandler returns an action or expression sequence of actions displaying the currently installed action (or actions) for the specified event (or events).

If called with no arguments, NumericEventHandler returns an expression sequence of equations displaying the currently installed actions for all events.

If called with the single argument default or exception, NumericEventHandler sets the actions for all events to the specified action, and returns an expression sequence of equations that gives the previously installed actions for all events, and which can be used as an argument to a subsequent call to NumericEventHandler to restore the previous state.

Whenever a change is made to event handling, whether by installing an event handler or by setting event handling to default or exception, the evalf remember table is cleared, since a change in event handling might change the result that a computation produces, rendering all remembered results invalid. Note: This also takes place when a procedure call returns, if the act of restoring the environment would change event handling.

The most recent Maple procedure in which an event was triggered (either explicitly by a call to NumericEvent, or implicitly by an internal numeric operation) is stored in the global variable NumericEventLocation. An event handler, or other code, can examine NumericEventLocation to help decide what to do next.  For example, one may want to install a handler that responds in a certain way to events in one's own code, but exhibits default behavior for events in library code.

If an event occurs at the top level, NumericEventLocation has the value NULL. If an event occurs in an anonymous procedure, NumericEventLocation has the value unknown.  Otherwise, its value is the name with which the offending procedure was invoked (possibly an escaped local, module export, table reference, and so on).

Computations within evalf impose a restriction on the type of the value returned by your handler. If a numeric event is triggered during an evalf operation and your handler is invoked, it must either raise an exception or return a floating-point value (including $Float\left(\mathrm{\infty }\right)$ and $Float\left(\mathrm{undefined}\right)$).  If the handler is invoked during complex floating-point computations and the handler is not raising an exception, it must return a complex floating-point value (including $Float\left(\mathrm{\infty }\right)+Float\left(\mathrm{\infty }\right)\mathrm{I}$, $1.+Float\left(\mathrm{\infty }\right)\mathrm{I}$, etc).

If your handler does not raise an exception, it should generally clear the corresponding status flag (see NumericStatus).

The routine NumericException can be used to ensure that the proper numeric exception is raised should you desire this behavior in your event handler.

Numeric events are signaled for operations involving hardware floating-point numbers, arbitrary precision software floating-point numbers, and exact numbers in the regular Maple computation environment. However, in the evalhf environment, in Compiled code, and in code generated for other environments by the CodeGeneration package, non-default numeric event handling settings are not guaranteed to be respected.

$f≔x\mapsto \ln \left(x-1\right)\:$

$\mathrm{NumericEventHandler}\left(\mathrm{division\_by\_zero}\right)$

$\mathrm{default}$

$f\left(1.0001\right)$

$\mathrm{-9.210340372}$

$\mathrm{NumericStatus}\left(\mathrm{division\_by\_zero}\right)$

$\mathrm{false}$

$f\left(1.0\right)$

$Float\left(-\mathrm{\infty }\right)$

$\mathrm{NumericStatus}\left(\mathrm{division\_by\_zero}\right)$

$\mathrm{true}$

$\mathrm{NumericStatus}\left(\mathrm{division\_by\_zero}=\mathrm{false}\right)\:$

$f\left(1\right)$

Error, (in ln) numeric exception: division by zero

$\mathrm{NumericEventHandler}\left(\mathrm{division\_by\_zero}=\mathrm{exception}\right)$

$\mathrm{division\_by\_zero}=\mathrm{default}$

$f\left(1.0\right)$

Error, (in `evalf/ln`) numeric exception: division by zero

MyHandler := proc(operator,operands,default_value)
   # MyHandler issues a warning, clears the status flag, and then
   # continues with the default value.
   WARNING("division by zero in %1 with argument(s) %2", operator, operands);
   NumericStatus( division_by_zero = false );
   return default_value;
end proc:

$\mathrm{NumericEventHandler}\left(\mathrm{division\_by\_zero}=\mathrm{MyHandler}\right)$

$\mathrm{division\_by\_zero}=\mathrm{exception}$

$f\left(1.0+0.\mathrm{I}\right)$

$Float\left(-\mathrm{\infty }\right)+Float\left(\mathrm{undefined}\right)\mathrm{I}$

$\mathrm{NumericStatus}\left(\mathrm{division\_by\_zero}\right)$

$\mathrm{false}$

$f\left(1\right)$

$-\mathrm{\infty }+\mathrm{undefined}\mathrm{I}$

$\mathrm{NumericEventHandler}\left(\right)$

$\mathrm{invalid\_operation}=\mathrm{default},\mathrm{division\_by\_zero}=\mathbf{proc}\left(\mathrm{operator}\,\mathrm{operands}\,\mathrm{default\_value}\right)\mathrm{WARNING}\left(''division\; by\; zero\; in\; \%1\; with\; argument(s)\; \%2''\,\mathrm{operator}\,\mathrm{operands}\right)\;\mathrm{NumericStatus}\left(\mathrm{division\_by\_zero}\=\mathrm{false}\right)\;\mathbf{return}\mathrm{default\_value}\mathbf{end\; proc},\mathrm{overflow}=\mathrm{default},\mathrm{underflow}=\mathrm{default},\mathrm{inexact}=\mathrm{default},\mathrm{real\_to\_complex}=\mathrm{default}$

g := proc(a,b) a / b end proc:

$g\left(3.0\,0.\right)$

$Float\left(\mathrm{\infty }\right)$

$\mathrm{NumericEventLocation}$

$g$

$f\left(1.0\right)$

$Float\left(-\mathrm{\infty }\right)$

$\mathrm{NumericEventLocation}$

$\mathrm{evalf/ln}$