Class MathContext

java.lang.Object
com.ibm.icu.math.MathContext
All Implemented Interfaces:
Serializable
public final class MathContext extends Object implements Serializable
The 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:

  1. digits: the number of digits (precision) to be used for an operation
  2. form: the form of any exponent that results from the operation
  3. lostDigits: whether checking for lost digits is enabled
  4. roundingMode: 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

    Fields
    Modifier and Type
    Field
    Description
    static final MathContext
    DEFAULT
    A MathContext object initialized to the default settings for general-purpose arithmetic.
    private static final int
    DEFAULT_DIGITS
     
    private static final int
    DEFAULT_FORM
     
    private static final boolean
    DEFAULT_LOSTDIGITS
     
    private static final int
    DEFAULT_ROUNDINGMODE
     
    (package private) int
    digits
    The number of digits (precision) to be used for an operation.
    static final int
    ENGINEERING
    Standard floating point notation (with engineering exponential format, where the power of ten is a multiple of 3).
    (package private) int
    form
    The form of results from an operation.
    (package private) boolean
    lostDigits
    Controls whether lost digits checking is enabled for an operation.
    private static final int
    MAX_DIGITS
     
    private static final int
    MIN_DIGITS
     
    static final int
    PLAIN
    Plain (fixed point) notation, without any exponent.
    static final int
    ROUND_CEILING
    Rounding mode to round to a more positive number.
    static final int
    ROUND_DOWN
    Rounding mode to round towards zero.
    static final int
    ROUND_FLOOR
    Rounding mode to round to a more negative number.
    static final int
    ROUND_HALF_DOWN
    Rounding mode to round to nearest neighbor, where an equidistant value is rounded down.
    static final int
    ROUND_HALF_EVEN
    Rounding mode to round to nearest neighbor, where an equidistant value is rounded to the nearest even neighbor.
    static final int
    ROUND_HALF_UP
    Rounding mode to round to nearest neighbor, where an equidistant value is rounded up.
    static final int
    ROUND_UNNECESSARY
    Rounding mode to assert that no rounding is necessary.
    static final int
    ROUND_UP
    Rounding mode to round away from zero.
    (package private) int
    roundingMode
    The rounding algorithm to be used for an operation.
    private static final int[]
    ROUNDS
     
    private static final String[]
    ROUNDWORDS
     
    static final int
    SCIENTIFIC
    Standard floating point notation (with scientific exponential format, where there is one digit before any decimal point).
    private static final long
    serialVersionUID
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    MathContext(int setdigits)
    Constructs a new MathContext with a specified precision.
    MathContext(int setdigits, int setform)
    Constructs a new MathContext with a specified precision and form.
    MathContext(int setdigits, int setform, boolean setlostdigits)
    Constructs a new MathContext with a specified precision, form, and lostDigits setting.
    MathContext(int setdigits, int setform, boolean setlostdigits, int setroundingmode)
    Constructs a new MathContext with a specified precision, form, lostDigits, and roundingMode setting.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    getDigits()
    Returns the digits setting.
    int
    getForm()
    Returns the form setting.
    boolean
    getLostDigits()
    Returns the lostDigits setting.
    int
    getRoundingMode()
    Returns the roundingMode setting.
    private static boolean
    isValidRound(int testround)
     
    String
    toString()
    Returns the MathContext as a readable string.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • PLAIN

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

    • SCIENTIFIC

      public static final int SCIENTIFIC
      Standard 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 a BigDecimal operation. A zero result in plain form may have a decimal part of one or more zeros.
      See Also:

    • ENGINEERING

      public static final int ENGINEERING
      Standard 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 a BigDecimal 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_CEILING
      Rounding mode to round to a more positive number. Used as a setting to control the rounding mode used during a BigDecimal 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_DOWN
      Rounding mode to round towards zero. Used as a setting to control the rounding mode used during a BigDecimal operation.

      All discarded digits are ignored (truncated). The result is neither incremented nor decremented.

      See Also:

    • ROUND_FLOOR

      public static final int ROUND_FLOOR
      Rounding mode to round to a more negative number. Used as a setting to control the rounding mode used during a BigDecimal 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_DOWN
      Rounding mode to round to nearest neighbor, where an equidistant value is rounded down. Used as a setting to control the rounding mode used during a BigDecimal 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_EVEN
      Rounding 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 a BigDecimal 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_UP
      Rounding mode to round to nearest neighbor, where an equidistant value is rounded up. Used as a setting to control the rounding mode used during a BigDecimal 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_UNNECESSARY
      Rounding mode to assert that no rounding is necessary. Used as a setting to control the rounding mode used during a BigDecimal 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_UP
      Rounding mode to round away from zero. Used as a setting to control the rounding mode used during a BigDecimal operation.

      If any of the discarded digits are non-zero then the result will be rounded up (away from zero).

      See Also:

    • digits

      int digits
      The 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 form
      The 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 lostDigits
      Controls whether lost digits checking is enabled for an operation. Set to true to enable checking, or to false to disable checking.

      When enabled, the BigDecimal operator methods check the precision of their operand or operands, and throw an ArithmeticException 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 roundingMode
      The 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 with ROUND_.

      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

      private static final String[] ROUNDWORDS

    • serialVersionUID

      private static final long serialVersionUID
      See Also:

    • DEFAULT

      public static final MathContext DEFAULT
      A MathContext 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 new MathContext with a specified precision. The other settings are set to the default values (see DEFAULT). An IllegalArgumentException is thrown if the setdigits parameter is out of range (<0 or >999999999).
      Parameters:
      setdigits - The int digits setting for this MathContext.
      Throws:
      IllegalArgumentException - parameter out of range.

    • MathContext

      public MathContext(int setdigits, int setform)
      Constructs a new MathContext with a specified precision and form. The other settings are set to the default values (see DEFAULT). An IllegalArgumentException is thrown if the setdigits parameter is out of range (<0 or >999999999), or if the value given for the setform parameter is not one of the appropriate constants.
      Parameters:
      setdigits - The int digits setting for this MathContext.
      setform - The int form setting for this MathContext.
      Throws:
      IllegalArgumentException - parameter out of range.

    • MathContext

      public MathContext(int setdigits, int setform, boolean setlostdigits)
      Constructs a new MathContext with a specified precision, form, and lostDigits setting. The roundingMode setting is set to its default value (see DEFAULT). An IllegalArgumentException is thrown if the setdigits parameter is out of range (<0 or >999999999), or if the value given for the setform parameter is not one of the appropriate constants.
      Parameters:
      setdigits - The int digits setting for this MathContext.
      setform - The int form setting for this MathContext.
      setlostdigits - The boolean lostDigits setting for this MathContext.
      Throws:
      IllegalArgumentException - parameter out of range.

    • MathContext

      public MathContext(int setdigits, int setform, boolean setlostdigits, int setroundingmode)
      Constructs a new MathContext with a specified precision, form, lostDigits, and roundingMode setting. An IllegalArgumentException is thrown if the setdigits parameter is out of range (<0 or >999999999), or if the value given for the setform or setroundingmode parameters is not one of the appropriate constants.
      Parameters:
      setdigits - The int digits setting for this MathContext.
      setform - The int form setting for this MathContext.
      setlostdigits - The boolean lostDigits setting for this MathContext.
      setroundingmode - The int roundingMode setting for this MathContext.
      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 the form setting. This will be one of ENGINEERING, PLAIN, or SCIENTIFIC.
      Returns:
      an int which is the value of the form setting

    • getLostDigits

      public boolean getLostDigits()
      Returns the lostDigits setting. This will be either true (enabled) or false (disabled).
      Returns:
      a boolean which is the value of the lostDigits setting

    • getRoundingMode

      public int getRoundingMode()
      Returns the roundingMode setting. This will be one of ROUND_CEILING, ROUND_DOWN, ROUND_FLOOR, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_HALF_UP, ROUND_UNNECESSARY, or ROUND_UP.
      Returns:
      an int which is the value of the roundingMode setting

    • toString

      public String toString()
      Returns the MathContext as a readable string. The String returned represents the settings of the MathContext object as four blank-delimited words separated by a single blank and with no leading or trailing blanks, as follows:
      1. digits=, immediately followed by the value of the digits setting as a numeric word.
      2. form=, immediately followed by the value of the form setting as an uppercase word (one of SCIENTIFIC, PLAIN, or ENGINEERING).
      3. lostDigits=, immediately followed by the value of the lostDigits setting (1 if enabled, 0 if disabled).
      4. 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.

      Overrides:
      toString in class Object
      Returns:
      a String representing the context settings.

    • isValidRound

      private static boolean isValidRound(int testround)