Class MathContext
- All Implemented Interfaces:
Serializable
MathContext
immutable class encapsulates the
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, which are not base-dependent, comprise:
digits
: the number of digits (precision) to be used for an operationform
: the form of any exponent that results from the operationlostDigits
: whether checking for lost digits is enabledroundingMode
: the algorithm to be used for rounding.
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
(9, SCIENTIFIC, false, ROUND_HALF_UP
).
In the BigDecimal
class, all methods which accept a
MathContext
object defaults) also have a version of the
method which does not accept a MathContext parameter. These versions
carry out unlimited precision fixed point arithmetic (as though the
settings were (0, PLAIN, false, ROUND_HALF_UP
).
The instance variables are shared with default access (so they are
directly accessible to the BigDecimal
class), but must
never be changed.
The rounding mode constants have the same names and values as the
constants of the same name in java.math.BigDecimal
, to
maintain compatibility with earlier versions of
BigDecimal
.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final MathContext
AMathContext
object initialized to the default settings for general-purpose arithmetic.private static final int
private static final int
private static final boolean
private static final int
(package private) int
The number of digits (precision) to be used for an operation.static final int
Standard floating point notation (with engineering exponential format, where the power of ten is a multiple of 3).(package private) int
The form of results from an operation.(package private) boolean
Controls whether lost digits checking is enabled for an operation.private static final int
private static final int
static final int
Plain (fixed point) notation, without any exponent.static final int
Rounding mode to round to a more positive number.static final int
Rounding mode to round towards zero.static final int
Rounding mode to round to a more negative number.static final int
Rounding mode to round to nearest neighbor, where an equidistant value is rounded down.static final int
Rounding mode to round to nearest neighbor, where an equidistant value is rounded to the nearest even neighbor.static final int
Rounding mode to round to nearest neighbor, where an equidistant value is rounded up.static final int
Rounding mode to assert that no rounding is necessary.static final int
Rounding mode to round away from zero.(package private) int
The rounding algorithm to be used for an operation.private static final int[]
private static final String[]
static final int
Standard floating point notation (with scientific exponential format, where there is one digit before any decimal point).private static final long
-
Constructor Summary
ConstructorsConstructorDescriptionMathContext
(int setdigits) Constructs a newMathContext
with a specified precision.MathContext
(int setdigits, int setform) Constructs a newMathContext
with a specified precision and form.MathContext
(int setdigits, int setform, boolean setlostdigits) Constructs a newMathContext
with a specified precision, form, and lostDigits setting.MathContext
(int setdigits, int setform, boolean setlostdigits, int setroundingmode) Constructs a newMathContext
with a specified precision, form, lostDigits, and roundingMode setting. -
Method Summary
Modifier and TypeMethodDescriptionint
Returns the digits setting.int
getForm()
Returns the form setting.boolean
Returns the lostDigits setting.int
Returns the roundingMode setting.private static boolean
isValidRound
(int testround) toString()
Returns theMathContext
as a readable string.
-
Field Details
-
PLAIN
public static final int PLAINPlain (fixed point) notation, without any exponent. Used as a setting to control the form of the result of aBigDecimal
operation. A zero result in plain form may have a decimal part of one or more zeros.- See Also:
-
SCIENTIFIC
public static final int SCIENTIFICStandard floating point notation (with scientific exponential format, where there is one digit before any decimal point). Used as a setting to control the form of the result of aBigDecimal
operation. A zero result in plain form may have a decimal part of one or more zeros.- See Also:
-
ENGINEERING
public static final int ENGINEERINGStandard floating point notation (with engineering exponential format, where the power of ten is a multiple of 3). Used as a setting to control the form of the result of aBigDecimal
operation. A zero result in plain form may have a decimal part of one or more zeros.- See Also:
-
ROUND_CEILING
public static final int ROUND_CEILINGRounding mode to round to a more positive number. Used as a setting to control the rounding mode used during aBigDecimal
operation.If any of the discarded digits are non-zero then the result should be rounded towards the next more positive digit.
- See Also:
-
ROUND_DOWN
public static final int ROUND_DOWNRounding mode to round towards zero. Used as a setting to control the rounding mode used during aBigDecimal
operation.All discarded digits are ignored (truncated). The result is neither incremented nor decremented.
- See Also:
-
ROUND_FLOOR
public static final int ROUND_FLOORRounding mode to round to a more negative number. Used as a setting to control the rounding mode used during aBigDecimal
operation.If any of the discarded digits are non-zero then the result should be rounded towards the next more negative digit.
- See Also:
-
ROUND_HALF_DOWN
public static final int ROUND_HALF_DOWNRounding mode to round to nearest neighbor, where an equidistant value is rounded down. Used as a setting to control the rounding mode used during aBigDecimal
operation.If the discarded digits represent greater than half (0.5 times) the value of a one in the next position then the result should be rounded up (away from zero). Otherwise the discarded digits are ignored.
- See Also:
-
ROUND_HALF_EVEN
public static final int ROUND_HALF_EVENRounding mode to round to nearest neighbor, where an equidistant value is rounded to the nearest even neighbor. Used as a setting to control the rounding mode used during aBigDecimal
operation.If the discarded digits represent greater than half (0.5 times) the value of a one in the next position then the result should be rounded up (away from zero). If they represent less than half, then the result should be rounded down.
Otherwise (they represent exactly half) the result is rounded down if its rightmost digit is even, or rounded up if its rightmost digit is odd (to make an even digit).
- See Also:
-
ROUND_HALF_UP
public static final int ROUND_HALF_UPRounding mode to round to nearest neighbor, where an equidistant value is rounded up. Used as a setting to control the rounding mode used during aBigDecimal
operation.If the discarded digits represent greater than or equal to half (0.5 times) the value of a one in the next position then the result should be rounded up (away from zero). Otherwise the discarded digits are ignored.
- See Also:
-
ROUND_UNNECESSARY
public static final int ROUND_UNNECESSARYRounding mode to assert that no rounding is necessary. Used as a setting to control the rounding mode used during aBigDecimal
operation.Rounding (potential loss of information) is not permitted. If any of the discarded digits are non-zero then an
ArithmeticException
should be thrown.- See Also:
-
ROUND_UP
public static final int ROUND_UPRounding mode to round away from zero. Used as a setting to control the rounding mode used during aBigDecimal
operation.If any of the discarded digits are non-zero then the result will be rounded up (away from zero).
- See Also:
-
digits
int digitsThe number of digits (precision) to be used for an operation. A value of 0 indicates that unlimited precision (as many digits as are required) will be used.The
BigDecimal
operator methods use this value to determine the precision of results. Note that leading zeros (in the integer part of a number) are never significant.digits
will always be non-negative. -
form
int formThe form of results from an operation.The
BigDecimal
operator methods use this value to determine the form of results, in particular whether and how exponential notation should be used.- See Also:
-
lostDigits
boolean lostDigitsControls whether lost digits checking is enabled for an operation. Set totrue
to enable checking, or tofalse
to disable checking.When enabled, the
BigDecimal
operator methods check the precision of their operand or operands, and throw anArithmeticException
if an operand is more precise than the digits setting (that is, digits would be lost). When disabled, operands are rounded to the specified digits. -
roundingMode
int roundingModeThe rounding algorithm to be used for an operation.The
BigDecimal
operator methods use this value to determine the algorithm to be used when non-zero digits have to be discarded in order to reduce the precision of a result. The value must be one of the public constants whose name starts withROUND_
.- See Also:
-
DEFAULT_FORM
private static final int DEFAULT_FORM- See Also:
-
DEFAULT_DIGITS
private static final int DEFAULT_DIGITS- See Also:
-
DEFAULT_LOSTDIGITS
private static final boolean DEFAULT_LOSTDIGITS- See Also:
-
DEFAULT_ROUNDINGMODE
private static final int DEFAULT_ROUNDINGMODE- See Also:
-
MIN_DIGITS
private static final int MIN_DIGITS- See Also:
-
MAX_DIGITS
private static final int MAX_DIGITS- See Also:
-
ROUNDS
private static final int[] ROUNDS -
ROUNDWORDS
-
serialVersionUID
private static final long serialVersionUID- See Also:
-
DEFAULT
AMathContext
object initialized to the default settings for general-purpose arithmetic. That is,digits=9 form=SCIENTIFIC lostDigits=false roundingMode=ROUND_HALF_UP
.- See Also:
-
-
Constructor Details
-
MathContext
public MathContext(int setdigits) Constructs a newMathContext
with a specified precision. The other settings are set to the default values (seeDEFAULT
). AnIllegalArgumentException
is thrown if thesetdigits
parameter is out of range (<0 or >999999999).- Parameters:
setdigits
- Theint
digits setting for thisMathContext
.- Throws:
IllegalArgumentException
- parameter out of range.
-
MathContext
public MathContext(int setdigits, int setform) Constructs a newMathContext
with a specified precision and form. The other settings are set to the default values (seeDEFAULT
). AnIllegalArgumentException
is thrown if thesetdigits
parameter is out of range (<0 or >999999999), or if the value given for thesetform
parameter is not one of the appropriate constants.- Parameters:
setdigits
- Theint
digits setting for thisMathContext
.setform
- Theint
form setting for thisMathContext
.- Throws:
IllegalArgumentException
- parameter out of range.
-
MathContext
public MathContext(int setdigits, int setform, boolean setlostdigits) Constructs a newMathContext
with a specified precision, form, and lostDigits setting. The roundingMode setting is set to its default value (seeDEFAULT
). AnIllegalArgumentException
is thrown if thesetdigits
parameter is out of range (<0 or >999999999), or if the value given for thesetform
parameter is not one of the appropriate constants.- Parameters:
setdigits
- Theint
digits setting for thisMathContext
.setform
- Theint
form setting for thisMathContext
.setlostdigits
- Theboolean
lostDigits setting for thisMathContext
.- Throws:
IllegalArgumentException
- parameter out of range.
-
MathContext
public MathContext(int setdigits, int setform, boolean setlostdigits, int setroundingmode) Constructs a newMathContext
with a specified precision, form, lostDigits, and roundingMode setting. AnIllegalArgumentException
is thrown if thesetdigits
parameter is out of range (<0 or >999999999), or if the value given for thesetform
orsetroundingmode
parameters is not one of the appropriate constants.- Parameters:
setdigits
- Theint
digits setting for thisMathContext
.setform
- Theint
form setting for thisMathContext
.setlostdigits
- Theboolean
lostDigits setting for thisMathContext
.setroundingmode
- Theint
roundingMode setting for thisMathContext
.- Throws:
IllegalArgumentException
- parameter out of range.
-
-
Method Details
-
getDigits
public int getDigits()Returns the digits setting. This value is always non-negative.- Returns:
- an
int
which is the value of the digits setting
-
getForm
public int getForm()- Returns:
- an
int
which is the value of the form setting
-
getLostDigits
public boolean getLostDigits()Returns the lostDigits setting. This will be eithertrue
(enabled) orfalse
(disabled).- Returns:
- a
boolean
which is the value of the lostDigits setting
-
getRoundingMode
public int getRoundingMode()Returns the roundingMode setting. This will be one ofROUND_CEILING
,ROUND_DOWN
,ROUND_FLOOR
,ROUND_HALF_DOWN
,ROUND_HALF_EVEN
,ROUND_HALF_UP
,ROUND_UNNECESSARY
, orROUND_UP
.- Returns:
- an
int
which is the value of the roundingMode setting
-
toString
Returns theMathContext
as a readable string. TheString
returned represents the settings of theMathContext
object as four blank-delimited words separated by a single blank and with no leading or trailing blanks, as follows:-
digits=
, immediately followed by the value of the digits setting as a numeric word. -
form=
, immediately followed by the value of the form setting as an uppercase word (one ofSCIENTIFIC
,PLAIN
, orENGINEERING
). -
lostDigits=
, immediately followed by the value of the lostDigits setting (1
if enabled,0
if disabled). -
roundingMode=
, immediately followed by the value of the roundingMode setting as a word. This word will be the same as the name of the corresponding public constant.
For example:
digits=9 form=SCIENTIFIC lostDigits=0 roundingMode=ROUND_HALF_UP
Additional words may be appended to the result of
toString
in the future if more properties are added to the class. -
-
isValidRound
private static boolean isValidRound(int testround)
-