Decimal Class

Contains methods for the Decimal primitive data type.

System

Two Decimal objects that are numerically equivalent but differ in scale (such as 1.1 and 1.10) generally do not have the same hashcode. Use caution when such Decimal objects are used in Sets or as Map keys.

For more information on Decimal, see Decimal Data Type.

• Rounding Mode

  Rounding mode specifies the rounding behavior for numerical operations capable of discarding precision.

• Decimal Methods

Rounding mode specifies the rounding behavior for numerical operations capable of discarding precision.

Each rounding mode indicates how the least significant returned digit of a rounded result is to be calculated. The following are the valid values for roundingMode.

Name	Description
CEILING	Rounds towards positive infinity. That is, if the result is positive, this mode behaves the same as the UP rounding mode; if the result is negative, it behaves the same as the DOWN rounding mode. Note that this rounding mode never decreases the calculated value. For example: Input number 5.5: CEILING round mode result: 6 Input number 1.1: CEILING round mode result: 2 Input number -1.1: CEILING round mode result: -1 Input number -2.7: CEILING round mode result: -2 For an example, see CEILING Rounding Mode Example.
DOWN	Rounds towards zero. This rounding mode always discards any fractions (decimal points) prior to executing. Note that this rounding mode never increases the magnitude of the calculated value. For example: Input number 5.5: DOWN round mode result: 5 Input number 1.1: DOWN round mode result: 1 Input number -1.1: DOWN round mode result: -1 Input number -2.7: DOWN round mode result: -2 For an example, see DOWN Rounding Mode Example.
FLOOR	Rounds towards negative infinity. That is, if the result is positive, this mode behaves the same as theDOWN rounding mode; if negative, this mode behaves the same as the UP rounding mode. Note that this rounding mode never increases the calculated value. For example: Input number 5.5: FLOOR round mode result: 5 Input number 1.1: FLOOR round mode result: 1 Input number -1.1: FLOOR round mode result: -2 Input number -2.7: FLOOR round mode result: -3 For an example, see FLOOR Rounding Mode Example.
HALF_DOWN	Rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case this mode rounds down. This rounding mode behaves the same as the UP rounding mode if the discarded fraction (decimal point) is > 0.5; otherwise, it behaves the same as DOWN rounding mode. For example: Input number 5.5: HALF_DOWN round mode result: 5 Input number 1.1: HALF_DOWN round mode result: 1 Input number -1.1: HALF_DOWN round mode result: -1 Input number -2.7: HALF_DOWN round mode result: -3 For an example, see HALF_DOWN Rounding Mode Example.
HALF_EVEN	Rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards the even neighbor. This rounding mode behaves the same as the HALF_UP rounding mode if the digit to the left of the discarded fraction (decimal point) is odd. It behaves the same as the HALF_DOWN rounding method if it is even. For example: Input number 5.5: HALF_EVEN round mode result: 6 Input number 1.1: HALF_EVEN round mode result: 1 Input number -1.1: HALF_EVEN round mode result: -1 Input number -2.7: HALF_EVEN round mode result: -3 For an example, see HALF_EVEN Rounding Mode Example. Note that this rounding mode statistically minimizes cumulative error when applied repeatedly over a sequence of calculations.
HALF_UP	Rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds up. This rounding method behaves the same as the UP rounding method if the discarded fraction (decimal point) is >= 0.5; otherwise, this rounding method behaves the same as the DOWN rounding method. For example: Input number 5.5: HALF_UP round mode result: 6 Input number 1.1: HALF_UP round mode result: 1 Input number -1.1: HALF_UP round mode result: -1 Input number -2.7: HALF_UP round mode result: -3 For an example, see HALF_UP Rounding Mode Example.
UNNECESSARY	Asserts that the requested operation has an exact result, which means that no rounding is necessary. If this rounding mode is specified on an operation that yields an inexact result, a MathException is thrown. For example: Input number 5.5: UNNECESSARY round mode result: MathException Input number 1.1: UNNECESSARY round mode result: MathException Input number 1.0: UNNECESSARY round mode result: 1 Input number -1.0: UNNECESSARY round mode result: -1 Input number -2.2: UNNECESSARY round mode result: MathException For an example, see UNNECESSARY Rounding Mode Example.
UP	Rounds away from zero. This rounding mode always truncates any fractions (decimal points) prior to executing. Note that this rounding mode never decreases the magnitude of the calculated value. For example: Input number 5.5: UP round mode result: 6 Input number 1.1: UP round mode result: 2 Input number -1.1: UP round mode result: -2 Input number -2.7: UP round mode result: -3 For an example, see UP Rounding Mode Example.

The following are methods for Decimal.

• abs()

  Returns the absolute value of the Decimal.

• divide(divisor, scale)

  Divides this Decimal by the specified divisor, and sets the scale, that is, the number of decimal places, of the result using the specified scale.

• divide(divisor, scale, roundingMode)

  Divides this Decimal by the specified divisor, sets the scale, that is, the number of decimal places, of the result using the specified scale, and if necessary, rounds the value using the rounding mode.

• doubleValue()

  Returns the Double value of this Decimal.

• format()

  Returns the String value of this Decimal using the locale of the context user.

• intValue()

  Returns the Integer value of this Decimal.

• longValue()

  Returns the Long value of this Decimal.

• pow(exponent)

  Returns the value of this decimal raised to the power of the specified exponent.

• precision()

  Returns the total number of digits for the Decimal.

• round()

  Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using half-even rounding mode, that is, it rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards the even neighbor.

• round(roundingMode)

  Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using the rounding mode specified by the rounding mode.

• scale()

  Returns the scale of the Decimal, that is, the number of decimal places.

• setScale(scale)

  Returns the Decimal scaled to the specified number of decimal places, using half-even rounding, if necessary. Half-even rounding mode rounds toward the “nearest neighbor.” If both neighbors are equidistant, the number is rounded toward the even neighbor.

• setScale(scale, roundingMode)

  Returns the Decimal scaled to the specified number of decimal places, using the specified rounding mode, if necessary.

• stripTrailingZeros()

  Returns the Decimal with any trailing zeros removed.

• toPlainString()

  Returns the String value of this Decimal, without using scientific notation.

• valueOf(doubleToDecimal)

  Returns a Decimal that contains the value of the specified Double.

• valueOf(longToDecimal)

  Returns a Decimal that contains the value of the specified Long.

• valueOf(stringToDecimal)

  Returns a Decimal that contains the value of the specified String. As in Java, the string is interpreted as representing a signed Decimal.

Returns the absolute value of the Decimal.

public Decimal abs()

Type: Decimal

Divides this Decimal by the specified divisor, and sets the scale, that is, the number of decimal places, of the result using the specified scale.

public Decimal divide(Decimal divisor, Integer scale)

• divisor: Type: Decimal
• scale: Type: Integer

Type: Decimal

Divides this Decimal by the specified divisor, sets the scale, that is, the number of decimal places, of the result using the specified scale, and if necessary, rounds the value using the rounding mode.

public Decimal divide(Decimal divisor, Integer scale, System.RoundingMode roundingMode)

• divisor: Type: Decimal
• scale: Type: Integer
• roundingMode: Type: System.RoundingMode

Type: Decimal

Returns the Double value of this Decimal.

public Double doubleValue()

Type: Double

Returns the String value of this Decimal using the locale of the context user.

public String format()

Type: String

Scientific notation will be used if an exponent is needed.

Returns the Integer value of this Decimal.

public Integer intValue()

Type: Integer

Returns the Long value of this Decimal.

public Long longValue()

Type: Long

Returns the value of this decimal raised to the power of the specified exponent.

public Decimal pow(Integer exponent)

• exponent: Type: Integer The value of exponent must be between 0 and 32,767.

Type: Decimal

If you use MyDecimal.pow(0), 1 is returned.

The Math.pow method does accept negative values.

Returns the total number of digits for the Decimal.

public Integer precision()

Type: Integer

For example, if the Decimal value was 123.45, precision returns 5. If the Decimal value is 123.123, precision returns 6.

Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using half-even rounding mode, that is, it rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards the even neighbor.

public Long round()

Type: Long

Note that this rounding mode statistically minimizes cumulative error when applied repeatedly over a sequence of calculations.

Returns the rounded approximation of this Decimal. The number is rounded to zero decimal places using the rounding mode specified by the rounding mode.

public Long round(System.RoundingMode roundingMode)

• roundingMode: Type: System.RoundingMode

Type: Long

Returns the scale of the Decimal, that is, the number of decimal places.

public Integer scale()

Type: Integer

Returns the Decimal scaled to the specified number of decimal places, using half-even rounding, if necessary. Half-even rounding mode rounds toward the “nearest neighbor.” If both neighbors are equidistant, the number is rounded toward the even neighbor.

public Decimal setScale(Integer scale)

• scale: Type: Integer The value of scale must be between –33 and 33. If the value of scale is negative, your unscaled value is multiplied by 10 to the power of the negation of scale. For example, after this operation, the value of d is 4*10^3.

Type: Decimal

If you do not explicitly set the scale for a Decimal, the item from which the Decimal is created determines the scale.

• If the Decimal is created as part of a query, the scale is based on the scale of the field returned from the query.
• If the Decimal is created from a String, the scale is the number of characters after the decimal point of the String.
• If the Decimal is created from a non-decimal number, the number is first converted to a String. The scale is then set using the number of characters after the decimal point.

Returns the Decimal scaled to the specified number of decimal places, using the specified rounding mode, if necessary.

public Decimal setScale(Integer scale, System.RoundingMode roundingMode)

• scale: Type: Integer
• roundingMode: Type: System.RoundingMode

Type: Decimal

If you do not explicitly set the scale for a Decimal, the item from which the Decimal is created determines the scale.

• If the Decimal is created as part of a query, the scale is based on the scale of the field returned from the query.
• If the Decimal is created from a String, the scale is the number of characters after the decimal point of the String.
• If the Decimal is created from a non-decimal number, the number is first converted to a String. The scale is then set using the number of characters after the decimal point.

Returns the Decimal with any trailing zeros removed.

public Decimal stripTrailingZeros()

Type: Decimal

Returns the String value of this Decimal, without using scientific notation.

public String toPlainString()

Type: String

Returns a Decimal that contains the value of the specified Double.

public static Decimal valueOf(Double doubleToDecimal)

• doubleToDecimal: Type: Double

Type: Decimal

Returns a Decimal that contains the value of the specified Long.

public static Decimal valueOf(Long longToDecimal)

• longToDecimal: Type: Long

Type: Decimal

Returns a Decimal that contains the value of the specified String. As in Java, the string is interpreted as representing a signed Decimal.

public static Decimal valueOf(String stringToDecimal)

• stringToDecimal: Type: String

Type: Decimal