mn8 Language Reference | Index

BigDecimal

SUMMARY:          DETAIL:

Description

Provides concepts for performing arbitrary-precision decimal arithmetic(BigDecimal). BigDecimal gives to the user complete control over rounding behavior and allows to to choose from comprehensive set of eight rounding modes.

Usage

            #create two BigDecimal 
            $A = BigDecimal.create("4657634753656543643")                                                                                  
            $B = BigDecimal.create("3352637875876768766")                                                                                  
            #Test BigDecimal methods
            print "    A/25 = " + $A.divide( BigDecimal.create("25"), "ROUND_DOWN" )                                                       
            print "    A(R) = " + $A.getRealValue                                                                                          
            print "    A(I) = " + $A.getIntegerValue                                                                                       
            print "A.max(B) = " + $A.max( $B )                                                                                             
            print "A.min(B) = " + $A.min( $B )                
            print "  A/1000 = " + $A.movePointLeft(3)                                                                                      
            print "   A*100 = " + $A.movePointRight(2)                                                                                     
            print "     A*B = " + $A.multiply( $B )                                                                                        
            print "      -A = " + $A.negate                                                                                                
            print "     A+B = " + $A.add( $B )                                                                                             
            print "     A-B = " + $A.subtract( $B )                                  

Constructor List

Method List

Detailed Constructor Info

Constructs a BigDecimal concept initialized with the value represented by the string given as parameter.

Detailed Method Info

Returns a BigDecimal whose value is the absolute value of this BigDecimal.

            $d = BigDecimal.create("-15.837")
            print $d.abs
            -- the result is --
            15.837
            

Returns a BigDecimal whose value is (this + $value).

            $d = BigDecimal.create("12.556")
            print $d.add(BigDecimal.create("2.444"))
            -- the result is --
            15.000
            

Compares this BigDecimal with the specified BigDecimal. Two BigDecimals that are equal in value but have a different scale (like 2.0 and 2.00) are considered equal by this method. Returns -1, 0 or 1 as this BigDecimal is numerically less than, equal to, or greater than $value.

            $d = BigDecimal.create("12.556")
            print $d.compareTo(BigDecimal.create("11.392"))
            print $d.compareTo(BigDecimal.create("12.556"))
            print $d.compareTo(BigDecimal.create("15.784"))
            -- the result is --
            1
            0
            -1
            

Returns a BigDecimal whose value is (this / $value). If rounding must be performed to generate a result with the given scale, the specified rounding mode is applied.This method working with ROUND_CEILING rounding mode only.

            $d = BigDecimal.create("13")
            print $d.divide(BigDecimal.create("3"))
            -- the result is --
            5
            

Returns a BigDecimal whose value is (this / $value). If rounding must be performed to generate a result with the given scale, the specified rounding mode will be applied.

            $d = BigDecimal.create("13")
            print $d.divide(BigDecimal.create("3"), "ROUND_DOWN")
            -- the result is --
            4
            

Compares this BigDecimal with the specified BigDecimal for equality. Unlike to the compareTo method, this method considers two BigDecimals equal only if they are equal in value and scale (so thus 2.0 is not equal to 2.00 when compared by this method).

            $d = BigDecimal.create("13.835")
            print $d.equals(BigDecimal.create("13.835"))
            print $d.equals(BigDecimal.create("13.8350"))
            -- the result is --
            true
            false
            

Converts this BigDecimal to a Integer. Standard narrowing primitive conversion as defined in The Java Language Specification: any fractional part of this BigDecimal will be discarded, and if the resulting "BigDecimal" is too big to fit in a Integer, only the low-order 64 bits are returned.

            $d = BigDecimal.create("13.835")
            print $d.getIntegerValue
            -- the result is --
            13
            

Converts this BigDecimal to a Real. Similar to the double-to-float narrowing primitive conversion defined in The Java Language Specification: if this BigDecimal has to great magnitude to represent as a Real, it will be converted to FLOAT.NEGATIVE_INFINITY or FLOAT.POSITIVE_INFINITY as appropriate.

            $d = BigDecimal.create("13.835")
            print $d.getRealValue
            -- the result is --
            13.835
            

Returns the rounding modes, which are:

• ROUND_UP
Rounding mode to round away from zero. Always increments the digit prior to a non-zero discarded fraction. Note that this rounding mode never decreases the magnitude of the calculated value.
• ROUND_DOWN
Rounding mode to round towards zero. Never increments the digit prior to a discarded fraction (i.e., truncates). Note that this rounding mode never increases the magnitude of the calculated value.
• ROUND_CEILING
Rounding mode to round towards positive infinity. If the BigDecimal is positive, behaves as for ROUND_UP; if negative, behaves as for ROUND_DOWN. Note that this rounding mode never decreases the calculated value.
• ROUND_FLOOR
Rounding mode to round towards negative infinity. If the BigDecimal is positive, behave as for ROUND_DOWN; if negative, behave as for ROUND_UP. Note that this rounding mode never increases the calculated value.
• ROUND_HALF_UP
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. Behaves as for ROUND_UP if the discarded fraction is >= .5; otherwise, behaves as for ROUND_DOWN. Note that this is the rounding mode that most of us were taught in grade school.
• ROUND_HALF_DOWN
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. Behaves as for ROUND_UP if the discarded fraction is > .5; otherwise, behaves as for ROUND_DOWN.
• ROUND_HALF_EVEN
Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor. Behaves as for ROUND_HALF_UP if the digit to the left of the discarded fraction is odd; behaves as for ROUND_HALF_DOWN if it's even. Note that this is the rounding mode that minimizes cumulative error when applied repeatedly over a sequence of calculations.
• ROUND_UNNECESSARY
Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary. If this rounding mode is specified on an operation that yields an inexact result, an ArithmeticException is thrown.

            $d = BigDecimal.create("13.835")
            print $d.getRoundingModes
            -- the result is --
            ROUND_UP
            ROUND_DOWN
            ROUND_CEILING
            ROUND_FLOOR
            ROUND_HALF_UP
            ROUND_HALF_DOWN
            ROUND_HALF_EVEN
            ROUND_UNNECESSARY
            

Returns the BigDecimal whose value is the greater of this BigDecimal and $value. If they are equal, as defined by the compareTo method, either may be returned.

            $d = BigDecimal.create("13.835")
            print $d.max(BigDecimal("13.836"))
            -- the result is --
            13.836
            

Returns the BigDecimal whose value is the lesser of this BigDecimal and $value. If they are equal, as defined by the compareTo method, either may be returned.

            $d = BigDecimal.create("13.835")
            print $d.min(BigDecimal("13.836"))
            -- the result is --
            13.835
            

Returns a BigDecimal which is equivalent to this one with the decimal point moved $n places to the left. If $n is non-negative, the call merely adds $n to the scale. If $n is negative, the call is equivalent to movePointRight(-$n). (The BigDecimal returned by this call has value (this * 10^-$n) and )

            $d = BigDecimal.create("13.835")
            print $d.movePointLeft(2)
            -- the result is --
            0.13835
            

Moves the decimal point the specified number of places to the right. If this BigDecimal's scale is >= $n, the call merely subtracts $n from the scale; otherwise, it sets the scale to zero, and multiplies the integer value by 10($n - this.scale). If $n is negative, the call is equivalent to movePointLeft(-$n). (The BigDecimal returned by this call has value (this * 10^$n) )

            $d = BigDecimal.create("13.835")
            print $d.movePointRight(2)
            -- the result is --
            1383.5
            

Returns a BigDecimal whose value is (this * $value).

            $d = BigDecimal.create("13.835")
            print $d.multiply(2)
            -- the result is --
            27.670
            

Returns a BigDecimal whose value is (-this).

            $d = BigDecimal.create("-13.835")
            print $d.negate
            -- the result is --
            13.835
            

Returns a BigDecimal whose value is (this - $value).

            $d = BigDecimal.create("13.835")
            print $d.substract(BigDecimal.create("3.83"))
            -- the result is --
            10.005