"

 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:'DivisionByZeroSignal DomainErrorSignal OverflowSignal

		UnderflowSignal ArithmeticSignal UnorderedSignal

		ConversionErrorSignal'

	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

	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

!

divisionByZeroSignal

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

    ^ ZeroDivide

!

domainErrorSignal

    "return the signal which is raised on math errors

     (such as log of 0 etc.)"

    ^ DomainError

!

imaginaryResultSignal

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

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

    ^ ImaginaryResultError

!

operationNotPossibleSignal

    ^ Error

!

overflowSignal

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

    ^ OverflowError

!

rangeErrorSignal

    "return the parent of the overflow/underflow signals"

    ^ RangeError

!

undefinedResultSignal

    ^ Error

!

underflowSignal

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

    ^ UnderflowError

!

unorderedSignal

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

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

    ^ UnorderedNumbersError

! !

!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.

! !

!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 infinity (for my instances)"

    ^ Infinity positive

!

nan

    "VW compatibility"

    ^ self NaN

!

negativeInfinity

    "return something which represents negative infinity (for my instances)"

    ^ Infinity negative

!

unity

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

     That is the neutral element for multiplication."

    self subclassResponsibility

!

zero

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

     That is the neutral element for addition."

    self subclassResponsibility

! !

!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:'queries'!

isAbstract

    "Return if this class is an abstract class.

     True is returned for ArithmeticValue here; false for subclasses.

     Abstract subclasses must redefine this again."

    ^ self == ArithmeticValue

! !

!ArithmeticValue methodsFor:'arithmetic'!

* something

    "return the product of the receiver and the argument."

    ^ self subclassResponsibility

!

+ something

    "return the sum of the receiver and the argument"

    ^ self subclassResponsibility

!

- something

    "return the difference of the receiver and the argument"

    ^ self subclassResponsibility

!

/ something

    "return the quotient of the receiver and the argument"

    ^ self subclassResponsibility

!

// something

    "return the integer quotient of dividing the receiver by aNumber with

     truncation towards negative infinity.

     Please be aware of the effect of truncation on negative receivers,

     and understand the difference between '//' vs. 'quo:'

     and the corresponding '\\' vs. 'rem:'"

    "/ Note: '^ (self / something) floor' may lead to infinite recursion

    ^ self subclassResponsibility

    "Modified: / 5.11.1996 / 11:46:27 / cg"

    "Modified: / 12.2.1998 / 16:31:36 / stefan"

!

\\ something

    "return the receiver modulo something.

     The remainder has the same sign as the argument, something.

     The following is always true:

        (receiver // something) * something + (receiver \\ something) = receiver

     Please be aware of the effect of truncation on negative receivers,

     and understand the difference between '//' vs. 'quo:'

     and the corresponding '\\' vs. 'rem:'."

    ^ self - ((self // something) * something)

   "

     0.9 \\ 0.4

     0.9 \\ -0.4

    -0.9 \\ 0.4

    -0.9 \\ -0.4

   "

    "Modified: / 12.2.1998 / 19:14:37 / stefan"

!

abs

    "return the absolute value of the receiver"

    (self negative) ifTrue:[^ self negated].

    ^ self

!

dist:arg

    "return the distance between the arg and the receiver."

    ^ (arg - self) abs

    "

     (1%1) dist:(0%0)

     (1@1) dist:(0@0)

     (1) dist:(0)

    "

!

modulusOf:aNumber

    "return aNumber modulo the receiver.

     The remainder has the same sign as something.

     Defined for protocol compatibility with ModuloNumber."

    ^ aNumber \\ self

!

negated

    "return the receiver negated"

    ^ self class zero - self

!

quo:something

    "Return the integer quotient of dividing the receiver by the argument

     with truncation towards zero.

     Please be aware of the effect of truncation on negative receivers,

     and understand the difference between '//' vs. 'quo:'

     and the corresponding '\\' vs. 'rem:'.

     The following is always true:

        (receiver quo: aNumber) * aNumber + (receiver rem: aNumber) = receiver

     For positive results, this is the same as #//,

     for negative results, the remainder is ignored.

     I.e.: '9 // 4 = 2' and '-9 // 4 = -3'

     in contrast: '9 quo: 4 = 2' and '-9 quo: 4 = -2'"

    ^ (self / something) truncated

!

reciprocal

    "return the receiver's reciprocal"

    ^ self class unity / self

!

rem:something

    "Return the integer remainder of dividing the receiver by the argument

     with truncation towards zero.

     The remainder has the same sign as the receiver.

     The following is always true:

        (receiver quo: something) * something + (receiver rem: something) = receiver

     Please be aware of the effect of truncation on negative receivers,

     and understand the difference between '//' vs. 'quo:'

     and the corresponding '\\' vs. 'rem:'."

    ^ self - ((self quo:something) * something)

!

uncheckedDivide:aNumber

    "return the quotient of the receiver and the argument, aNumber.

     Do not check for divide by zero (return NaN or Infinity).

     This operation is provided for emulators of other languages/semantics,

     where no exception is raised for these results (i.e. Java).

     It is only defined if the argument's type is the same as the receiver's."

    aNumber isZero ifTrue:[

        self isZero ifTrue:[^ self class NaN].

        self negative ifTrue:[^ self class negativeInfinity].

        ^ self class infinity.

    ].

    ^ self / aNumber

! !

!ArithmeticValue methodsFor:'arithmetic destructive'!

*= aNumber

    "Return the product of self multiplied by aNumber.

     The receiver MAY, but NEED NOT be changed to contain the product.

     So this method must be used as: 'a := a *= 5'.

     This method can be redefined for constructed datatypes to do optimisations"

    ^ self * aNumber

    "Created: / 28.4.1999 / 11:46:11 / stefan"

    "Modified: / 28.4.1999 / 11:53:28 / stefan"

!

+= aNumber

    "Return the sum of self and aNumber.

     The receiver MAY, but NEED NOT be changed to contain the sum.

     So this method must be used as: 'a := a += 5'.

     This method can be redefined for constructed datatypes to do optimisations"

    ^ self + aNumber

    "Created: / 28.4.1999 / 10:13:41 / stefan"

    "Modified: / 28.4.1999 / 11:54:11 / stefan"

!

-= aNumber

    "Return the difference of self and aNumber.

     The receiver MAY, but NEED NOT be changed to contain the difference.

     So this method must be used as: 'a := a -= 5'.

     This method can be redefined for constructed datatypes to do optimisations"

    ^ self - aNumber

    "Created: / 28.4.1999 / 10:13:58 / stefan"

    "Modified: / 28.4.1999 / 11:54:37 / stefan"

!

/= aNumber

    "Return the quotient of self and aNumber.

     The receiver MAY, but NEED NOT be changed to contain the quotient.

     So this method must be used as: 'a := a /= 5'.

     This method can be redefined for constructed datatypes to do optimisations"

    ^ self / aNumber

    "Created: / 28.4.1999 / 11:46:22 / stefan"

    "Modified: / 28.4.1999 / 11:55:06 / stefan"

!

div2

    "Return the quotient of self divided by 2.

     The receiver MAY, but NEED NOT be changed to contain the result.

     So this method must be used as: 'a := a div2.

     This method can be redefined for constructed datatypes to do optimisations"

    ^ self // 2

    "Created: / 28.4.1999 / 10:12:44 / stefan"

    "Modified: / 28.4.1999 / 11:56:09 / stefan"

!

mul2

    "Return the product of self multiplied by 2.

     The receiver MAY, but NEED NOT be changed to contain the result.

     So this method must be used as: a := a mul2.

     This method can be redefined for constructed datatypes to do optimisations"

    ^ self * 2

    "Created: / 28.4.1999 / 10:12:55 / stefan"

    "Modified: / 28.4.1999 / 11:56:38 / stefan"

! !

!ArithmeticValue methodsFor:'coercing & converting'!

coerce:aNumber

    "convert the argument aNumber into an instance of the receiver's class and return it."

    ^ self subclassResponsibility

!

generality

    "return a number giving the receiver's generality.

     That number is used to convert one of the arguments in a mixed expression.

     The generality has to be defined in subclasses,