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