Class: FixedPoint

• Inheritance
• Description
• Related information
• Class protocol
  • constants
  • instance creation
  • printing control
  • queries
• Instance protocol
  • accessing
  • arithmetic
  • coercing & converting
  • double dispatching
  • mathematical functions
  • printing & storing
  • private
  • testing
  • truncation & rounding
• Examples

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--ArithmeticValue
         |
         +--Number
            |
            +--Fraction
               |
               +--FixedPoint

Category:

Magnitude-Numbers

Version:

rev: 1.36 date: 2006/11/22 12:24:37

user: cg

file: FixedPoint.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Jan Steinman, Bytesmiths

adapted, modified & enhanced by Claus Gittinger

Description:

This class implements infinite precision fixed-point numbers,
which internally hold exact (fractional) results, but print themself with
a limited number of digits after the decimal point (rounded). 

NOTICE:
    it seems that squeak prints these truncated,
    whereas ST/X prints them rounded.
    This behavior should probably be controllable by providing      
    a subclass (RoundedFixedPoint ?) which redefines the printOn: method.
    (it is now controlled by a classVar, which is of course not a thread-safe
    solution).

These can be used in computation, where rounding errors should not accumulate,
but only a limited precision is required for the final result.
(i.e. business applications)

It doesn't really do anything too interesting except creating instances, 
converting, and printing, since its superclass Fraction does all the work.

Test: 
    '123456789012345678901234567890.123456789' asFixedPoint * 1000000000
    -> 123456789012345678901234567890123456789'

Notes: 1) The current implementation does not convert arbitrarily-based 
          String representations, which shouldn't be too much a problem 
          for financial types.

       2) the implementation is a hack - it has not been optimized for speed
          in particular.

Mixed mode arithmetic:
    fix op fix       -> fix, scale is max. of operands
    fix op fraction  -> fix; scale is fix's scale
    fix op integer   -> fix; scale is fix's scale
    fix op float     -> float

Related information:

    Number
    Fraction
    Integer
    Float
    ShortFloat
    LongFloat
    Complex

Class protocol:

 pi

pi with 1000 valid digits...

 numerator: n denominator: d

 numerator: n denominator: d scale: s

 readFrom: aStringOrStream

return the next FixedPoint from the (character-)stream aStream.

NOTICE:
This behaves different from the default readFrom:, in returning
0 (instead of raising an error) in case no number can be read.
It is unclear, if this is the correct behavior (ST-80 does this)
- depending on the upcoming ANSI standard, this may change.

 readFrom: aStringOrStream onError: exceptionBlock

return an instance of me as described on the string or stream, aStringOrStream.
If an error occurs during conversion, return the result
from evaluating exceptionBlock

 printTruncated

 printTruncated: aBoolean

 exponentCharacter

Instance protocol:

 scale

return the number of places of significance that is carried by the receiver.

 * aNumber

return the product of the receiver and the argument, aNumber.
Redefined to care for the scale if the argument is another fixPoint number.
The results scale is the maximum of the receivers scale and the arguments scale.

 + aNumber

return the sum of the receiver and the argument, aNumber.
Redefined to care for the scale if the argument is another fixPoint number.
The results scale will be the maximum of the receivers and the arguments scale.

 - aNumber

return the difference of the receiver and the argument, aNumber.
Redefined to care for the scale if the argument is another fixPoint number.
The results scale is the maximum of the receivers scale and the arguments scale.

 / aNumber

return the quotient of the receiver and the argument, aNumber.
Redefined to care for the scale if the argument is another fixPoint number.
The results scale is the maximum of the receivers scale and the arguments scale.

 negated

redefined from Fraction to preserve scale

 reciprocal

redefined from Fraction to preserve scale

 asFixedPoint

return the receiver as a fixedPoint number - thats the receiver itself

 asFixedPoint: newScale

return a fixedPoint with the same value as the receiver,
and newScale number of post-decimal digits

 asFraction

return the receiver as a fraction

 coerce: aNumber

return aNumber converted into receivers type

 generality

return the generality value - see ArithmeticValue>>retry:coercing:

 differenceFromFixedPoint: aFixedPoint

 differenceFromFraction: aFraction

 differenceFromInteger: anInteger

sent when an integer does not know how to subtract the receiver.
Redefined here to preserve the scale.

 productFromFixedPoint: aFixedPoint

 productFromFraction: aFraction

 productFromInteger: anInteger

sent when an integer does not know how to multiply the receiver.
Redefined here to preserve the scale.

 quotientFromFixedPoint: aFixedPoint

Return the quotient of the argument, aFixedPoint and the receiver.

 quotientFromFraction: aFraction

Return the quotient of the argument, aFraction and the receiver.
Sent when aFraction does not know how to divide by the receiver.
Redefined here to preserve the scale.

 quotientFromInteger: anInteger

Return the quotient of the argument, anInteger and the receiver.
Sent when anInteger does not know how to divide by the receiver.
Redefined here to preserve the scale.

 sumFromFixedPoint: aFixedPoint

 sumFromFraction: aFraction

 sumFromInteger: anInteger

sent when an integer does not know how to add the receiver.
Redefined here to preserve the scale.

 sqrt

compute the square root, using the Newton method.
The approximated return value has an error less than
the receivers last digit, as specified in the scale.

 printDecimalOn: aStream roundToScale: roundToScale truncateToScale: truncateToScale

common helper for printing (with round or truncate)
and storing (neither rounding, nor truncating)

 printOn: aStream

append to the argument, aStream, a printed representation of the receiver.
For printout, only scale post-decimal digits are printed
(By default, the printout is rounded to that many digits)

 printRoundedOn: aStream

append to the argument, aStream, a printed representation of the receiver.
For printout, only scale post-decimal digits are printed,
the printout is rounded to that many digits

 printTruncatedOn: aStream

append to the argument, aStream, a printed representation of the receiver.
For printout, only scale post-decimal digits are printed,
the printout is truncated to that many digits

 storeOn: aStream

notice: we MUST preserve the full internal precision when storing/reloading

 storeString

 reduced

 scale: newScale

set the scale.

 setNumerator: nInteger denominator: d scale: s

initialize the instance variables.
Assumes that the fraction as specified by numerator and denominator
is already reduced.

 setNumerator: nInteger scale: s

initialize the instance variables.
Assumes that the fraction as specified by numerator and denominator
is already reduced.

 setScale: newScale

initialize the scale instance variables.

 isFixedPoint

return true, if the receiver is some kind of fixedPoint number;
true is returned here - the method is redefined from Object.

 roundedToScale

return the receiver rounded to my scale
(i.e. return a number which has the value which is shown when printing)

 truncatedToScale

return the receiver truncated towards zero to my scale

Examples:

     |a b r|

     a := (FixedPoint fromString:'123.456').
     b := '1.10' asFixedPoint.
     r := a + b.
     Transcript showCR:r.
     Transcript showCR:(r withScale:2).
     Transcript showCR:(r withScale:1).
     Transcript showCR:(r rounded).

     |a b r|

     a := (FixedPoint fromString:'0.9999999').
     b := 0.0000001 asFixedPoint. 
     r := a + b.
     Transcript showCR:r.
     Transcript showCR:(r withScale:2).
     Transcript showCR:(r withScale:1).
     Transcript showCR:(r rounded).

     |a b r|

     a := (FixedPoint fromString:'0.9999998').
     b := (FixedPoint fromString:'0.0000001').
     r := a + b.
     Transcript showCR:r.
     Transcript showCR:(r withScale:2).
     Transcript showCR:(r withScale:1).
     Transcript showCR:(r rounded).

     |a b r|

     a := (FixedPoint fromString:'1.0').
     b := (FixedPoint fromString:'0.0000001').
     r := a + b.
     Transcript showCR:r.
     Transcript showCR:(r withScale:2).
     Transcript showCR:(r withScale:1).
     Transcript showCR:(r rounded).

     |a b r|

     a := (FixedPoint fromString:'0.99').
     b := (FixedPoint fromString:'0.0000001').
     r := a + b.
     Transcript showCR:r.
     Transcript showCR:(r withScale:2).
     Transcript showCR:(r withScale:1).
     Transcript showCR:(r rounded).