ArciMath BigDecimal v2.05
now with BigDecimalFormat

be.arci.math
Class MathContext

java.lang.Object
  |
  +--be.arci.math.MathContext
All Implemented Interfaces:
java.io.Serializable

public final class MathContext
extends java.lang.Object
implements java.io.Serializable

The immutable class MathContext contains the arithmetic settings understood by the operator methods of the BigDecimal class (and potentially other classes). Operator methods are those that effect an operation on a number or a pair of numbers.

The settings comprise:

digits
the precision or number of decimal digits to be used for the operands of an operation and it's result.
form
the notation or form of any exponent that results from the operation.
lostDigits
whether operands should be checked not to loose digits when they are rounded before an operation is performed on them.
roundingMode
the rule to be used for rounding operands to and result of an operation.
When provided, a MathContext object supplies the settings for an operation directly.

When MathContext.DEFAULT is provided for a MathContext parameter then the default settings are used, to know digits=9, form=SCIENTIFIC, lostDigits=false, roundingMode=ROUND_HALF_UP.

All methods of the BigDecimal class which accept a MathContext parameter also have a signature of the method which does not accept a MathContext parameter; the methods with that signature carry out unlimited precision fixed point arithmetic, as with the settings digits=0, form=PLAIN, lostDigits=false, roundingMode=ROUND_HALF_UP. This provides backward compatibility with the java.math.BigDecimal class.

The rounding mode can have the same values as the ROUND_ constants of java.math.BigDecimal and be.arci.math.BigDecimal, to ease switching over. We recommend using the definitions for these constants that are in this class.

See Also:
BigDecimal, Serialized Form

Field Summary
static MathContext DEFAULT
          The default context, which is digits=9, form=SCIENTIFIC, lostDigits=false, roundingMode=ROUND_HALF_UP, settings well suited for general-purpose arithmetic.
static int ENGINEERING
          Floating point notation (with engineering exponential format, having one to three digits before any decimal point, such that the power of ten in an eventual exponent is a multiple of 3).
static int PLAIN
          Plain fixed point notation, without any exponent.
static int ROUND_CEILING
          Rounding mode to round towards positive infinity.
static int ROUND_DOWN
          Rounding mode to round towards zero.
static int ROUND_FLOOR
          Rounding mode to round towards negative infinity.
static int ROUND_HALF_DOWN
          Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
static int ROUND_HALF_EVEN
          Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
static int ROUND_HALF_UP
          Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
static int ROUND_UNNECESSARY
          Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary.
static int ROUND_UP
          Rounding mode to round away from zero.
static int SCIENTIFIC
          Floating point notation (with scientific exponential format, where there is one digit before any decimal point).
 
Constructor Summary
MathContext(int digits)
          Constructs a new MathContext with a specified precision.
MathContext(int digits, int form)
          Constructs a new MathContext with a specified precision and form of notation.
MathContext(int digits, int form, boolean swLostDigits)
          Constructs a new MathContext with a specified precision, form of notation and assertion for lost digits.
MathContext(int digits, int form, boolean swLostDigits, int roundingMode)
          Constructs a new MathContext with a specified precision, form of notation, assertion for lost digits and rounding mode.
 
Method Summary
 int getDigits()
          Returns the precision in digits; this value is always non-negative.
 int getForm()
          Returns the form or notation setting; this will be one of the constants ENGINEERING, PLAIN or SCIENTIFIC.
 boolean getLostDigits()
          Returns the lostDigits assertion setting.
 int getRoundingMode()
          Returns the rounding mode setting; this will be one of the ROUND_ constants
 java.lang.String toString()
          Returns the MathContext as a readable string.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

PLAIN

public static final int PLAIN
Plain fixed point notation, without any exponent. Used as a setting to control the notation of the result of a BigDecimal operation. A zero result in plain form may have a decimal part of one or more zeros, like "0.00".
See Also:
SCIENTIFIC, ENGINEERING

SCIENTIFIC

public static final int SCIENTIFIC
Floating point notation (with scientific exponential format, where there is one digit before any decimal point). Used as a setting to control the notation of the result of a BigDecimal operation.
See Also:
PLAIN, ENGINEERING

ENGINEERING

public static final int ENGINEERING
Floating point notation (with engineering exponential format, having one to three digits before any decimal point, such that the power of ten in an eventual exponent is a multiple of 3). Used as a setting to control the notation of the result of a BigDecimal operation.
See Also:
SCIENTIFIC, PLAIN

ROUND_UP

public static final int 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. This and the other rounding mode constants are maintained in the be.arci.math.BigDecimal class for backward compatibility with java.lang.BigDecimal, but they are more at home in the MathContext class.
See Also:
BigDecimal.ROUND_UP

ROUND_DOWN

public static final int 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.
See Also:
BigDecimal.ROUND_DOWN

ROUND_CEILING

public static final int 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.
See Also:
BigDecimal.ROUND_CEILING

ROUND_FLOOR

public static final int 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.
See Also:
BigDecimal.ROUND_FLOOR

ROUND_HALF_UP

public static final int 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.
See Also:
BigDecimal.ROUND_HALF_UP

ROUND_HALF_DOWN

public static final int 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.
See Also:
BigDecimal.ROUND_HALF_DOWN

ROUND_HALF_EVEN

public static final int 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.
See Also:
BigDecimal.ROUND_HALF_EVEN

ROUND_UNNECESSARY

public static final int 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.
See Also:
BigDecimal.ROUND_UNNECESSARY

DEFAULT

public static final MathContext DEFAULT
The default context, which is digits=9, form=SCIENTIFIC, lostDigits=false, roundingMode=ROUND_HALF_UP, settings well suited for general-purpose arithmetic.
Constructor Detail

MathContext

public MathContext(int digits)
Constructs a new MathContext with a specified precision. The other settings are as in DEFAULT.
Parameters:
digits - The precision in digits for this MathContext; must be in the range 0 ≤ digits ≤ 999999999.
Throws:
java.lang.IllegalArgumentException - parameter out of range.
See Also:
DEFAULT

MathContext

public MathContext(int digits,
                   int form)
Constructs a new MathContext with a specified precision and form of notation. The other settings are as in DEFAULT.
Parameters:
digits - The precision in digits for this MathContext; must be in the range 0 ≤ digits ≤ 999999999.
form - The form or notation for this MathContext, which must be one of the constants PLAIN, SCIENTIFIC or ENGINEERING.
Throws:
java.lang.IllegalArgumentException - parameter out of range.
See Also:
DEFAULT, PLAIN, SCIENTIFIC, ENGINEERING

MathContext

public MathContext(int digits,
                   int form,
                   boolean swLostDigits)
Constructs a new MathContext with a specified precision, form of notation and assertion for lost digits. The rounding mode is set as in DEFAULT.
Parameters:
digits - The precision in digits for this MathContext; must be in the range 0 ≤ digits ≤ 999999999.
form - The form or notation for this MathContext, which must be one of the constants PLAIN, SCIENTIFIC or ENGINEERING.
lostDigits - true if assertion for not loosing non-zero digits is needed.
Throws:
java.lang.IllegalArgumentException - parameter out of range.
See Also:
DEFAULT, PLAIN, SCIENTIFIC, ENGINEERING

MathContext

public MathContext(int digits,
                   int form,
                   boolean swLostDigits,
                   int roundingMode)
Constructs a new MathContext with a specified precision, form of notation, assertion for lost digits and rounding mode.
Parameters:
digits - The precision in digits for this MathContext; must be in the range 0 ≤ digits ≤ 999999999.
form - The form or notation for this MathContext, which must be one of the constants PLAIN, SCIENTIFIC or ENGINEERING.
lostDigits - true if assertion for not loosing non-zero digits is needed.
roundingMode - The roundingMode setting for this MathContext, which must be one of the ROUND_ constants.
Throws:
java.lang.IllegalArgumentException - parameter out of range.
See Also:
PLAIN, SCIENTIFIC, ENGINEERING
Method Detail

getDigits

public int getDigits()
Returns the precision in digits; this value is always non-negative.

getForm

public int getForm()
Returns the form or notation setting; this will be one of the constants ENGINEERING, PLAIN or SCIENTIFIC.
See Also:
PLAIN, SCIENTIFIC, ENGINEERING

getLostDigits

public boolean getLostDigits()
Returns the lostDigits assertion setting.

getRoundingMode

public int getRoundingMode()
Returns the rounding mode setting; this will be one of the ROUND_ constants

toString

public java.lang.String toString()
Returns the MathContext as a readable string.
Overrides:
toString in class java.lang.Object

ArciMath BigDecimal v2.05
now with BigDecimalFormat