Class: FixedDecimal

• Inheritance
• Description
• Class protocol
  • coercing & converting
  • constants
  • instance creation
• Instance protocol
  • accessing
  • arithmetic
  • coercing & converting
  • comparing
  • converting
  • double dispatching
  • inspecting
  • mathematical functions
  • printing
  • private
  • testing
  • truncation and round off

Inheritance:

   Object
   |
   +--Magnitude
      |
      +--ArithmeticValue
         |
         +--Number
            |
            +--FixedDecimal

Package:

stx:libbasic2

Category:

Magnitude-Numbers

Version:

rev: 1.22 date: 2023/12/12 14:37:13

user: stefan

file: FixedDecimal.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Author:

Chris Cunningham

ported to ST/X by cg;

added handling of scale 0,

reading from string w.o. decimal point,

different coercing scheme in ST/X

Description:

A FixedDecimal is similar to a ScaledDecimal, but different in certain ways.  
It's primary purpose was to be able to represent precise decimals 
for such things as representing money 
- where ScaledDecimals leave something to be desired.  

For instance, with ScaledDecimals, you get:
    (33.333s withScale:2) + (33.333s withScale:2)   
and print it yields: 
    66.67s 
but with FixedDecimals, you would get:
    (33.333 asFixedDecimal: 2) + (33.333 asFixedDecimal: 2)         
and print it yields: 
    66.66.

So, FixedDecimals automatically round the numbers to the exact scale you specify,
whereas ScaledDecimals keep the correct value internally and only round when printing
or when asked explicitly via roundedToScale.

Converting a float to a FixedDecimal and back will not necessarily 
return the starting number, unlike ScaledDecimals.

Instance Variables
    negative:       Indicates wheither the FixedDecimal is negative.  
                    Used for printing internally.
    scaledNumber:   A raw scaled integer representing the number multiplied by 10^scale.
    integerPart:    The integer part of the number.
    fractionPart:   The non-integer part of the number.
    scale:          The scale of the FixedDecimal

Based on Squeak public domain code.

Class protocol:

 coerce: aNumber

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

 generality

when combined with a ScaledDecimal, we generate FixedDecimals

Usage example(s):

FixedDecimal generality 66 ScaledDecimal generality 65

 zero

(comment from inherited method)
return something which represents the zero element (for my instances).
That is the neutral element for addition.

 newFromFixedDecimal: aDecimal scale: newScale

Answer a new instance of me with a possibly different scale.
If the new scale is smaller than aDecimal's scale,
the new fixedDcimal is rounded to that smaller scale

 newFromFixedDecimal: aDecimal scale: newScale truncated: truncatedBoolean

Answer a new instance of me with a possibly different scale.
If the new scale is smaller than aDecimal's scale,
the new fixedDcimal is rounded (or truncated) to that smaller scale

 newFromNumber: aNumber scale: scaleIn

Answer a new instance of me.

Usage example(s):

FixedDecimal newFromNumber:1.234 scale:3 -> 1.234 FixedDecimal newFromNumber:1.234 scale:2 -> 1.23 FixedDecimal newFromNumber:1.234 scale:1 -> 1.2 FixedDecimal newFromNumber:1.234 scale:0 -> 1 FixedDecimal newFromNumber:1.987 scale:3 -> 1.987 FixedDecimal newFromNumber:1.987 scale:2 -> 1.99 FixedDecimal newFromNumber:1.987 scale:1 -> 2.0 FixedDecimal newFromNumber:1.987 scale:0 -> 2

 newFromNumber: aNumber scale: scaleIn truncated: truncatedBoolean

Answer a new instance of me.

Usage example(s):

FixedDecimal newFromNumber:1.234 scale:3 -> 1.234 FixedDecimal newFromNumber:1.234 scale:2 -> 1.23 FixedDecimal newFromNumber:1.234 scale:1 -> 1.2 FixedDecimal newFromNumber:1.234 scale:0 -> 1 FixedDecimal newFromNumber:1.987 scale:3 -> 1.987 FixedDecimal newFromNumber:1.987 scale:2 -> 1.99 FixedDecimal newFromNumber:1.987 scale:1 -> 2.0 FixedDecimal newFromNumber:1.987 scale:0 -> 2

 newFromString: aNumberString

Answer a new instance of me.
String is assumed to be of the format: '293492.230', '293492.' or '293492'

Usage example(s):

self newFromString:'1234.56' -> 1234.56 self newFromString:'1234.5' -> 1234.5 self newFromString:'1234.' -> 1234 self newFromString:'1234' -> 1234

 newFromString: aNumberString scale: scaleIn

Answer a new instance of me.
String is assumed to be of the format: '293492.230', '293492.' or '293492'

Usage example(s):

self newFromString:'1234.56' scale:2 self newFromString:'1234.56' scale:nil

 newFromString: aNumberString scale: scaleIn decimalPointCharacters: decimalPointCharacters

Answer a new instance of me.
String is assumed to be of the format:
'293492.230', '293492.' or '293492'

Usage example(s):

self newFromString:'1234.563' scale:2 -> 1234.56 self newFromString:'1234.567' scale:2 -> 1234.57 self newFromString:'1234.567' scale:5 -> 1234.56700 self newFromString:'1234.56 ' scale:5 -> 1234.56000 self newFromString:'1234.56' scale:nil -> 1234.56 self newFromString:'1234.5' scale:nil -> 1234.5 self newFromString:'1234.' scale:nil -> 1234.0 self newFromString:'1234' scale:nil -> 1234 self newFromString:'1234' scale:-1 -> 1234

 readFrom: aString

compatability with ScaledDecimal

Usage example(s):

ScaledDecimal readFrom: '123.456' -> 123.456 ScaledDecimal readFrom: '123.45' -> 123.45 ScaledDecimal readFrom: '123.4' -> 123.4 ScaledDecimal readFrom: '123.' -> 123 ScaledDecimal readFrom: '123' -> 123 FixedDecimal readFrom: '123.456' -> 123.456 FixedDecimal readFrom: '123.45' -> 123.45 FixedDecimal readFrom: '123.4' -> 123.4 FixedDecimal readFrom: '123.' -> 123 FixedDecimal readFrom: '123' -> 123

 readFrom: aString decimalPointCharacters: decimalPointCharacters

compatability with ScaledDecimal

Usage example(s):

ScaledDecimal readFrom: '123,456' decimalPointCharacters:',' -> 123.456 ScaledDecimal readFrom: '123,45' decimalPointCharacters:',' -> 123.45 ScaledDecimal readFrom: '123,4' decimalPointCharacters:',' -> 123.4 ScaledDecimal readFrom: '123,' decimalPointCharacters:',' -> 123 ScaledDecimal readFrom: '123' decimalPointCharacters:',' -> 123 FixedDecimal readFrom: '123,456' decimalPointCharacters:',' -> 123.456 FixedDecimal readFrom: '123,45' decimalPointCharacters:',' -> 123.45 FixedDecimal readFrom: '123,4' decimalPointCharacters:',' -> 123.4 FixedDecimal readFrom: '123,' decimalPointCharacters:',' -> 123 FixedDecimal readFrom: '123' decimalPointCharacters:',' -> 123

Instance protocol:

 negative

return true if the receiver is less than zero.

 scale

 * operand

(comment from inherited method)
return the product of the receiver and the argument.

 + operand

(comment from inherited method)
return the sum of the receiver and the argument

 - operand

another fixed decimal and same scale

 / operand

Modified (format): / 08-11-2021 / 15:26:31 / Stefan_Vogel

 // operand

Anser the integer quotient after dividing the receiver by operand
with truncation towards negative infinity.

 asInteger

(comment from inherited method)
return an integer with same value - might truncate

 asSignedInteger

 negated

0.050 asFixedDecimal:2 -> 0.05
(0.050 asFixedDecimal:2) negated -> -0.05

0.054 asFixedDecimal:2 -> 0.05
(0.054 asFixedDecimal:2) negated -> -0.05
(0.054 asFixedDecimal:2) negated asFloat -> -0.05

(0.0 asFixedDecimal:2) -> 0.00
(0.0 asFixedDecimal:2) negated -> 0.00

 reciprocal

0.050 asFixedDecimal:2 -> 0.05
(0.050 asFixedDecimal:2) reciprocal -> 20.00

0.054 asFixedDecimal:2 -> 0.05
(0.054 asFixedDecimal:2) reciprocal -> 20.00

Usage example(s):

0.050 asScaledDecimal:2 -> 0.05 (0.050 asScaledDecimal:2) reciprocal -> 20.00 0.054 asScaledDecimal:2 -> 0.05 (0.054 asScaledDecimal:2) reciprocal -> 18.52

 coerce: aNumber

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

Usage example(s):

'1.234' asFixedPoint scale ('1.234' asFixedDecimal) coerce:1

 generality

when combined with a ScaledDecimal, we generate FixedDecimals

Usage example(s):

FixedDecimal generality 66 ScaledDecimal generality 65

 < aNumber

(comment from inherited method)
Compare the receiver with the argument and return true if the
receiver is less than the argument. Otherwise return false.

 = aNumber

(comment from inherited method)
Compare the receiver with the argument and return true if the
receiver is equal to the argument. Otherwise return false.

 hash

(comment from inherited method)
instances, for which #= answers true must answer the same hash

 asAbbreviatedString

Show us in [normal], MIL, BIL, TRIL, as appropriate.

Usage example(s):

(123456 asFixedDecimal:2) asAbbreviatedString -> '123456' (1234567 asFixedDecimal:2) asAbbreviatedString -> '1.23 MIL' (12345678 asFixedDecimal:2) asAbbreviatedString -> '12.35 MIL' (123456789 asFixedDecimal:2) asAbbreviatedString -> '123.46 MIL' (1234567890 asFixedDecimal:2) asAbbreviatedString -> '1.23 BIL' (12345678901 asFixedDecimal:2) asAbbreviatedString ->'12.35 BIL' (123456789012 asFixedDecimal:2) asAbbreviatedString -> '123.46 BIL' (1234567890123 asFixedDecimal:2) asAbbreviatedString -> '1.23 TRIL' (12345678901234 asFixedDecimal:2) asAbbreviatedString -> '12.35 TRIL' (123456789012345 asFixedDecimal:2) asAbbreviatedString -> '123.46 TRIL'

 asAbbreviatedStringUsing: milBilTrilSuffixArray

Show us in [normal], MIL, BIL, TRIL, as appropriate.

 asFloat

(1.23 asFixedDecimal:2) -> 1.23
(1.23 asFixedDecimal:2) asFloat -> 1.23
(1.23 asFixedDecimal:2) negated -> -1.23
(1.23 asFixedDecimal:2) negated asFloat -> -1.23

 asFraction

(1.23 asFixedDecimal:2) -> 1.23
(1.23 asFixedDecimal:2) asFraction -> (123/100)
(1.23 asFixedDecimal:2) negated -> -1.23
(1.23 asFixedDecimal:2) negated asFraction -> (-123/100)

 withScale: newScale

return a new FixedDecimal with my value but a different scale

 equalFromFixedDecimal: decimal

(comment from inherited method)
aFixedDecimal does not know how to compare to the receiver -
retry the operation by coercing to higher generality

 lessFromFixedDecimal: aFixedDecimal

(1000 asFixedDecimal:1) > 60
(60 asFixedDecimal:1) > 60
(1000 asFixedDecimal:1) > (60 asFixedDecimal:2)
(60 asFixedDecimal:1) > (60 asFixedDecimal:2)
(1000 asFixedDecimal:2) > (60 asFixedDecimal:1)
(60 asFixedDecimal:2) > (60 asFixedDecimal:1)

 inspectorExtraAttributes
( an extension from the stx:libtool package )

extra (pseudo instvar) entries to be shown in an inspector.

 cbrt

return the cubic root of myself.

 exp

return e raised to the power of the receiver

Usage example(s):

(1 asFixedDecimal:100) exp

 sqrt

return the square root of myself.

 printOn: aStream

(comment from inherited method)
append a printed description of the receiver to aStream

 printOn: aStream base: base

(comment from inherited method)
return a string representation of the receiver in the specified
radix (without the initial XXr)

 printOn: aStream precision: precise

 printOn: aStream precision: precise reserveSign: boolean

ReserveSign, if true, means that if we are not negative, then we should preceed the number with a 0. So that the numbers will ALWAYS be the same size when printed.

 printString

(comment from inherited method)
return a string for printing the receiver.
Since we now use printOn: as the basic print mechanism,
we have to create a stream and print into it.

 greaterThanFixedDecimal: decimal scaleDiff: scaleDiff

 integerPart

 scaledFractionPart

 scaledNumber

 setPart1: part1In part2: part2In scale: scaleIn negative: aBoolean

 setPart1: part1In part2: part2In scale: scaleIn negative: aBoolean number: realNumber

 usedMagnitude

 usedScale

 isFixedDecimal

 asFixedDecimal: aScale

return a fixedDecimal approximating the receiver's value
to scale fractional digits

 fractionPart

the fractionPart represents the part after the decimal point
such that:
(self truncated + self fractionPart) = self

 roundedToScale: newScale

return a new fixedDecimal, rounded to another scale.

Usage example(s):

1.235 asFixedDecimal:3 -> 1.235 (1.235 asFixedDecimal:3) roundedToScale:2 -> 1.24 (1.235 asFixedDecimal:3) roundedToScale:3 -> 1.235 1.23456 asFixedDecimal:3 -> 1.235 (1.23456 asFixedDecimal:3) roundedToScale:2 -> 1.24

 truncated

return the receiver truncated towards zero as an integer

Usage example(s):

(12.345 asFixedDecimal:3) truncated -> 12 (-12.345 asFixedDecimal:3) truncated -> 12

 truncatedToScale

I am already rounded to my scale, so this is a noop.
This is provided for protocol compatibility with ScaledDecimals

Usage example(s):

1.23456 asScaledDecimal:3 1.235 (1.23456 asScaledDecimal:3) roundedToScale 1.235 1.23456 asFixedDecimal:3 1.235 (1.23456 asFixedDecimal:3) roundedToScale 1.235 (1.23456 asFixedDecimal:3) truncatedToScale 1.235

 truncatedToScale: newScale

return a new fixedDecimal, truncated to another scale.

Usage example(s):

1.23456 asScaledDecimal:3 1.235 (1.23456 asScaledDecimal:3) roundedToScale 1.235 1.23456 asFixedDecimal:3 1.235 (1.23456 asFixedDecimal:3) roundedToScale 1.235 (1.23456 asFixedDecimal:3) truncatedToScale 1.235 (1.23456 asFixedDecimal:3) truncatedToScale:2 1.23