Agena

2.32.0, September 24, 2022 - Added six arithmetic binary operators that detect potential numeric overflow, underflow and division by zero and allow the user to invoke proper self-written functions that handle them: `inc` for addition, `dec` for subtraction, `mul` for multiplication, `div` for division and `intdiv` for integer division, plus `mod` for modulus. The operators after checking possible exceptions call user-defined handlers along with the operands and information on the kind of exception: `inc` calls `math.add`, `dec` calls `math.subtract`, `mul` calls `math.multiply`, `div` calls `math.divide`, `intdiv` calls `math.intdivide` and `mod` calls `math.modulo` (not `math.modulus`). Two examples: Division: the handler might look like this (`math.intdivide` and `math.modulo` may be similar, since the values for `kind` are the same): > math.divide := proc(n, d, kind) is > case kind > of 0b000 then return n/d # no exception > of 0b001 then error('division by zero') # denominator is zero, do not return `undefined` but throw an exception > of 0b010 then error('underflow') # very large value to be divided by very small value close to 0 > of 0b100 then return n/d # both numerator and denominator are close to 0 > esac > end; > 1 div 0: division by zero See Chapter 4.6.8 and 14.2 of the Primer and Reference for more examples, including addition and multiplication. The threshold that defines whether a value is `close to zero` can be set with `environ.kernel/closetozero`, which by default is `DoubleEps`, e.g.: > environ.kernel(closetozero = 1e-20); The type of numerical exception that occurred the last time one the six new operators has been invoked can also be queried by calling the new function `environ.arithstate` which returns the type of exception as a bit field, see case/of clauses above: > 1e308 inc 1e308: overflow > environ.arithstate(): 1 - Added various constants with a precision of 1,000 digits to the arbitrary precision MAPM package: Pi, E, sqrt(2), ln(2), Golden Ratio, etc. See the Primer and Reference, Chapter 11.3, for a list. - `mapm.xnumber` now accepts a second optional argument, the precision, that will be used for the specific value to be defined. The default still is 20. - In OS/2 and DOS, the `mapm` package did not correctly clean up memory, causing lost bytes at exit. This has been fixed. - Included examples on how to use the MAPM package in the Primer and Reference.