"

 COPYRIGHT (c) 1993 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libbasic' }"

"{ NameSpace: Smalltalk }"

Magnitude subclass:#ArithmeticValue

	instanceVariableNames:''

	classVariableNames:'ArithmeticSignal ConversionErrorSignal DivisionByZeroSignal

		DomainErrorSignal OverflowSignal UnderflowSignal UnorderedSignal'

	poolDictionaries:''

	category:'Magnitude-Numbers'

!

!ArithmeticValue class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1993 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    ArithmeticValue is an abstract superclass for all things responding to

    arithmetic messages. It was inserted into the hierarchy, to allow objects

    like matrices, functions etc. to share the arithmetic methods defined here.

    Notice, that what used to be signals are now exception classes - the class

    variables and signal accessors remain here for backward compatibility.

    [class variables:]

        ArithmeticSignal        <Error>         parent of all arithmetic signals

                                                (never raised itself)

                                                New: now a reference to ArithmeticError

        DomainErrorSignal       <Error>         raised upon float errors

                                                (for example range in trigonometric)

                                                New: now a reference to DomainError; no longer a classVar

        DivisionByZeroSignal    <Error>         raised when division by 0 is attempted

                                                New: now a reference to ZeroDivide

        OverflowSignal          <Error>         raised on overflow/underflow conditions

        UnderflowSignal                         in float arithmetic.

                                                Notice: some OperatingSystems do not

                                                provide enough information for ST/X to

                                                extract the real reason for the floatException

                                                thus raising DomainErrorSignal in these cases.

    [author:]

        Claus Gittinger

    [See also:]

        Number

"

! !

!ArithmeticValue class methodsFor:'Signal constants'!

arithmeticSignal

    "return the parent of all arithmetic signals"

    ^ ArithmeticError

!

coercionErrorSignal

    ^ ArithmeticError

    "Created: / 26-01-2019 / 10:53:12 / Claus Gittinger"

!

divisionByZeroSignal

    "return the signal which is raised on division by zero.

     No longer used - we now have the class based ZeroDivide exception.

     This method is kept for backward compatibility."

    ^ ZeroDivide

    "Modified (comment): / 20-06-2017 / 17:53:33 / cg"

!

domainErrorSignal

    "return the signal which is raised on some math errors,

     when the argument is outside the legal domain.

     (such as arcSin of 2 etc.)"

    ^ DomainError

    "

     2 arcSin

     0 log     - raises infiniteResult, which is a child of DomainError

    "

    "Modified (comment): / 22-09-2017 / 09:50:41 / cg"

!

imaginaryResultSignal

    "return the signal which is raised when an imaginary result would be created

     (such as when taking the sqrt of a negative number).

     This error can be handled by wrapping the computation inside a trapImaginary

     block; then, a complex result is generated."

    ^ ImaginaryResultError

    "

     -2 sqrt

     Complex trapImaginary:[ -2 sqrt ]

    "

    "Modified (comment): / 22-09-2017 / 09:53:58 / cg"

!

infiniteResultSignal

    "return the signal which is raised when an infinite result would be created.

     This is a subclass of DomainError.

     (such as when taking the logarithm of zero)"

    ^ InfiniteResultError

    "Created: / 03-07-2017 / 15:46:02 / cg"

    "Modified (comment): / 22-09-2017 / 09:49:15 / cg"

!

operationNotPossibleSignal

    ^ ArithmeticError

    "Modified: / 26-01-2019 / 10:54:35 / Claus Gittinger"

!

overflowSignal

    "return the signal which is raised on overflow conditions (in floats).

     Attention: currently not raised on all architectures; some return NaN"

    ^ OverflowError

    "

     10e300 * 10e30

     10q300 * 10e30

    "

    "Modified (comment): / 22-09-2017 / 09:58:49 / cg"

!

rangeErrorSignal

    "return the parent of the overflow/underflow signals"

    ^ RangeError

!

undefinedResultSignal

    ^ ArithmeticError

    "Modified: / 26-01-2019 / 10:54:28 / Claus Gittinger"

!

underflowSignal

    "return the signal which is raised on underflow conditions (in floats)

     Attention: currently not raised on all architectures; some return zero"

    ^ UnderflowError

    "

     10e-300 / 10e30

    "

    "Modified (comment): / 22-09-2017 / 09:58:57 / cg"

!

unorderedSignal

    "return the signal which is raised when numbers are compared,

     for which no ordering is defined (for example: complex numbers)"

    ^ UnorderedNumbersError

    "

     (0 + 3i) > (0 + 4i)

     3i > 4i

    "

    "Modified (comment): / 22-09-2017 / 09:57:28 / cg"

! !

!ArithmeticValue class methodsFor:'class initialization'!

initialize

    "setup the signals"

    "/ Notice that we now use class based exceptions;

    "/ however, for backward compatibility, the class variables

    "/ referring to those are kept for a while, for subclass compatibility.

    "/ Please convert your code to access those via the Signal-constants class

    "/ messages (accessors) instead of referring to the class variables.

    ArithmeticSignal := ArithmeticError.

    "/ DomainErrorSignal := DomainError.

    DivisionByZeroSignal := ZeroDivide.

    UnorderedSignal := UnorderedNumbersError.

    ConversionErrorSignal := ConversionError.

    OverflowSignal := OverflowError.

    UnderflowSignal := UnderflowError.

    "Modified: / 03-07-2017 / 14:05:10 / cg"

! !

!ArithmeticValue class methodsFor:'coercing & converting'!

coerce:aNumber

    "convert the argument aNumber into an instance of the receiver (class) and return it."

    ^ self subclassResponsibility

! !

!ArithmeticValue class methodsFor:'constants'!

NaN

    "return the constant NaN (not a Number)."

    ^ NotANumber new

!

infinity

    "return something which represents positive infinity.

     Warning: do not compare equal against infinities;

     instead, check using isFinite or isInfinite"

    ^ Infinity positive

    "Modified (comment): / 20-06-2017 / 13:45:23 / cg"

    "Modified (comment): / 09-06-2019 / 12:56:30 / Claus Gittinger"

!

nan

    "VW compatibility"

    ^ self NaN

!

negativeInfinity

    "return something which represents negative infinity.

     Warning: do not compare equal against infinities;

     instead, check using isFinite or isInfinite"

    ^ Infinity negative

    "Modified (comment): / 09-06-2019 / 12:56:36 / Claus Gittinger"

!

positiveInfinity

    "return something which represents positive infinity.

     Warning: do not compare equal against infinities;

     instead, check using isFinite or isInfinite"

    ^ self infinity

    "Created: / 09-06-2019 / 12:49:31 / Claus Gittinger"

!

unity

    "return something which represents the unity element (for my instances).

     That is the neutral element for multiplication."

    ^ self subclassResponsibility

    "Modified: / 16-06-2017 / 11:04:36 / cg"

!

zero

    "return something which represents the zero element (for my instances).

     That is the neutral element for addition."

    ^ self subclassResponsibility

    "Modified: / 16-06-2017 / 11:04:33 / cg"

! !

!ArithmeticValue class methodsFor:'error reporting'!

raise:aSignalSymbolOrErrorClass receiver:someNumber selector:sel arguments:argArray errorString:text 

    "ST-80 compatible signal raising. Provided for PD numeric classes.

     aSignalSymbolOrErrorClass is either an Error-subclass, or

     the selector which is sent to myself, to retrieve the Exception class / Signal."

    <context: #return>

    |msg signalOrException|

    msg := MessageSend

                receiver:someNumber

                selector:sel

                arguments:argArray.

    aSignalSymbolOrErrorClass isSymbol ifTrue:[

        signalOrException := self perform:aSignalSymbolOrErrorClass.

    ] ifFalse:[

        signalOrException := aSignalSymbolOrErrorClass.    "/ assume its an Error-Subclass

    ].

    ^ signalOrException

         raiseRequestWith:msg 

         errorString:text 

         in:thisContext sender

    "

     Number 

        raise:#domainErrorSignal

        receiver:1.0

        selector:#foo 

        errorString:'foo bar test'

    "

    "Modified: / 16.11.2001 / 14:12:09 / cg"

! !

!ArithmeticValue class methodsFor:'exception handling'!

trapImaginary:aBlock

    "evaluate aBlock; 

     if any ImaginaryResult occurs inside, which would return an imaginary result, 

     (eg. square root of negative number),

     convert the result to a complex number and proceed.

     This allows for regular (failing) code to transparently convert to complex."

    ^ ImaginaryResultError 

        handle: [:ex |

            |msgSend selector rcvr|

            msgSend := ex parameter.

            selector := msgSend selector.

            rcvr := msgSend receiver.

            (selector == #sqrt or: [selector == #sqrtTruncated]) ifTrue: [

                (rcvr isNumber and:[rcvr isReal]) ifTrue:[

                    ex proceedWith:(rcvr abs perform:selector) i

                ] ifFalse:[    

                    msgSend receiver: rcvr asComplex.

                    ex proceedWith: msgSend value

                ].

            ] ifFalse: [

                (selector == #integerSqrt) ifTrue: [

                    (rcvr isInteger) ifTrue:[

                        ex proceedWith:(rcvr abs integerSqrt) i

                    ] ifFalse:[

                        ex proceedWith:(rcvr abs asComplex sqrt floor) i

                    ].    

                ] ifFalse: [

                    (selector == #nthRoot:) ifTrue: [

                        ex proceedWith:(rcvr abs nthRoot:msgSend argument) i

                    ]

                ]

            ].

            ex reject

        ] do: 

            aBlock

    "

     this raises an error:

         -2 sqrt

     this returns an imaginary result:

         Complex trapImaginary: [-2 sqrt]

     of course, this one as well:

         -2 asComplex sqrt

    "

    "failing code:

         |a|

         a := -2.

         (a sqrt + 5) * 17.

    "

    "complex code:

         |a|

         Complex trapImaginary:[

             a := -2.

             (a sqrt + 5) * 2.

         ]

    "

    "Modified: / 22-09-2017 / 10:18:14 / cg"

!

trapInfinity:aBlock

    "evaluate aBlock; 

     if any DomainError occurs inside, which would return an infinite result, 

     (eg. ln of zero),

     convert the result to infinity and proceed.

     This allows for regular (failing) code to transparently convert to infinity and behave

     similar to other systems which do that."

    ^ InfiniteResultError 

        handle: [:ex |

            |msgSend selector rcvr|

            msgSend := ex parameter.

            selector := msgSend selector.

            rcvr := msgSend receiver.

            ((selector == #ln) 

            or:[selector == #log10

            or:[selector == #integerLog10]]) ifTrue: [

                (rcvr isNumber) ifTrue:[

                    ex proceedWith:(rcvr class negativeInfinity )

                ].

            ].

            ex reject

        ] do: 

            aBlock

    "

     this raises an error:

         0 ln

     this returns an imaginary result:

         Number trapInfinity: [0 ln]

    "

    "failing code:

         |a|

         a := 0.

         a ln isFinite.

    "

    "fixed code:

         |a|

         Number trapInfinity:[

             a := 0.

             a ln isFinite.

         ]

    "

    "Created: / 03-07-2017 / 14:25:57 / cg"

    "Modified: / 03-07-2017 / 15:53:40 / cg"

!

trapOverflow:aBlock

    "evaluate aBlock; 

     if an Overflow occurs inside, return INF and proceed."

    ^ OverflowError 

        handle: [:ex |

            |msgSend rcvr|

            msgSend := ex parameter.

            rcvr := msgSend receiver.

            ex proceedWith:(rcvr class positiveInfinity)

        ] do: 

            aBlock

    "

     this raises an error:

         1000 factorial asShortFloat

     this returns an imaginary result:

         Number trapOverflow: [ 1000 factorial asShortFloat]

    "

    "Created: / 07-07-2017 / 13:08:06 / cg"

    "Modified: / 09-06-2019 / 12:53:55 / Claus Gittinger"

!

trapUnderflow:aBlock

    "evaluate aBlock; 

     if an Underflow occurs inside, return zero and proceed."