Apex Reference Guide
jDecimal Class
Contains methods for the Decimal primitive data type.
Namespace
Usage
For more information on Decimal, see Decimal Data Type.
Rounding Mode
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:
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:
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:
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:
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:
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:
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:
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:
For an example, see UP Rounding Mode Example. |
CEILING Rounding Mode Example
1Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
2Long[] expected = new Long[]{6, 2, -1, -2};
3for(integer x = 0; x < example.size(); x++){
4 System.assertEquals(expected[x],
5 example[x].round(System.RoundingMode.CEILING));
6}DOWN Rounding Mode Example
1Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
2Long[] expected = new Long[]{5, 1, -1, -2};
3for(integer x = 0; x < example.size(); x++){
4 System.assertEquals(expected[x],
5 example[x].round(System.RoundingMode.DOWN));
6}FLOOR Rounding Mode Example
1Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
2Long[] expected = new Long[]{5, 1, -2, -3};
3for(integer x = 0; x < example.size(); x++){
4 System.assertEquals(expected[x],
5 example[x].round(System.RoundingMode.FLOOR));
6}HALF_DOWN Rounding Mode Example
1Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
2Long[] expected = new Long[]{5, 1, -1, -3};
3for(integer x = 0; x < example.size(); x++){
4 System.assertEquals(expected[x],
5 example[x].round(System.RoundingMode.HALF_DOWN));
6}HALF_EVEN Rounding Mode Example
1Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
2Long[] expected = new Long[]{6, 1, -1, -3};
3for(integer x = 0; x < example.size(); x++){
4 System.assertEquals(expected[x],
5 example[x].round(System.RoundingMode.HALF_EVEN));
6}HALF_UP Rounding Mode Example
1Decimal[] example = new Decimal[]{5.5, 1.1, -1.1, -2.7};
2Long[] expected = new Long[]{6, 1, -1, -3};
3for(integer x = 0; x < example.size(); x++){
4 System.assertEquals(expected[x],
5 example[x].round(System.RoundingMode.HALF_UP));
6}UNNECESSARY Rounding Mode Example
1Decimal example1 = 5.5;
2Decimal example2 = 1.0;
3system.assertEquals(1,
4 example2.round(System.RoundingMode.UNNECESSARY));
5try{
6 example1.round(System.RoundingMode.UNNECESSARY);
7} catch(Exception E) {
8 system.assertEquals('System.MathException', E.getTypeName());
9}Decimal Methods
The following are methods for Decimal.
abs()
Returns the absolute value of the Decimal.
Signature
public Decimal abs()
Return Value
Type: Decimal
Example
1Decimal myDecimal = -6.02214129;
2System.assertEquals(6.02214129, myDecimal.abs());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.
Signature
public Decimal divide(Decimal divisor, Integer scale)
Return Value
Type: Decimal
Example
1Decimal decimalNumber = 19;
2Decimal result = decimalNumber.divide(100, 3);
3System.assertEquals(0.190, result);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.
Signature
public Decimal divide(Decimal divisor, Integer scale, System.RoundingMode roundingMode)
Parameters
- divisor
- Type: Decimal
- scale
- Type: Integer
- roundingMode
- Type: System.RoundingMode
Return Value
Type: Decimal
Example
1Decimal myDecimal = 12.4567;
2Decimal divDec = myDecimal.divide(7, 2, System.RoundingMode.UP);
3System.assertEquals(divDec, 1.78);doubleValue()
Returns the Double value of this Decimal.
Signature
public Double doubleValue()
Return Value
Type: Double
Example
1Decimal myDecimal = 6.62606957;
2Double value = myDecimal.doubleValue();
3System.assertEquals(6.62606957, value);format()
Returns the String value of this Decimal using the locale
of the context user.
Signature
public String format()
Return Value
Type: String
Usage
Scientific notation will be used if an exponent is needed.
Example
1// U.S. locale
2Decimal myDecimal = 12345.6789;
3system.assertEquals('12,345.679', myDecimal.format());intValue()
Returns the Integer value of this Decimal.
Signature
public Integer intValue()
Return Value
Type: Integer
Example
1Decimal myDecimal = 1.602176565;
2system.assertEquals(1, myDecimal.intValue());longValue()
Returns the Long value of this Decimal.
Signature
public Long longValue()
Return Value
Type: Long
Example
1Decimal myDecimal = 376.730313461;
2system.assertEquals(376, myDecimal.longValue());pow(exponent)
Returns the value of this decimal raised to the power of
the specified exponent.
Signature
public Decimal pow(Integer exponent)
Parameters
- exponent
- Type: Integer
- The value of exponent must be between 0 and 32,767.
Return Value
Type: Decimal
Usage
If you use MyDecimal.pow(0), 1 is returned.
The Math.pow method does accept negative values.
Example
1Decimal myDecimal = 4.12;
2Decimal powDec = myDecimal.pow(2);
3System.assertEquals(powDec, 16.9744);precision()
Returns the total number of digits for the Decimal.
Signature
public Integer precision()
Return Value
Type: Integer
Example
For example, if the Decimal value was 123.45, precision returns 5. If the Decimal value is 123.123, precision returns 6.
1Decimal D1 = 123.45;
2Integer precision1 = D1.precision();
3system.assertEquals(precision1, 5);
4Decimal D2 = 123.123;
5Integer precision2 = D2.precision();
6system.assertEquals(precision2, 6);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.
Signature
public Long round()
Return Value
Type: Long
Usage
Note that this rounding mode statistically minimizes cumulative error when applied repeatedly over a sequence of calculations.
Example
1Decimal D = 4.5;
2Long L = D.round();
3System.assertEquals(4, L);
4
5Decimal D1 = 5.5;
6Long L1 = D1.round();
7System.assertEquals(6, L1);
8
9Decimal D2 = 5.2;
10Long L2 = D2.round();
11System.assertEquals(5, L2);
12
13Decimal D3 = -5.7;
14Long L3 = D3.round();
15System.assertEquals(-6, L3);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.
Signature
public Long round(System.RoundingMode roundingMode)
Parameters
- roundingMode
- Type: System.RoundingMode
Return Value
Type: Long
scale()
Returns the scale of the Decimal, that is, the number of
decimal places.
Signature
public Integer scale()
Return Value
Type: Integer
Example
1Decimal myDecimal = 9.27400968;
2system.assertEquals(8, myDecimal.scale());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.
Signature
public Decimal setScale(Integer scale)
Parameters
- 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.
1Decimal d = 4000; 2d = d.setScale(-3);
Return Value
Type: Decimal
Usage
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.
Example
1Decimal myDecimal = 8.987551787;
2Decimal setScaled = myDecimal.setscale(3);
3System.assertEquals(8.988, setScaled);setScale(scale, roundingMode)
Returns the Decimal scaled to the specified number of decimal places, using the specified
rounding mode, if necessary.
Signature
public Decimal setScale(Integer scale, System.RoundingMode roundingMode)
Parameters
- 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.
1Decimal d = 4000; 2d = d.setScale(-3); - roundingMode
- Type: System.RoundingMode
Return Value
Type: Decimal
Usage
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.
stripTrailingZeros()
Returns the Decimal with any trailing zeros removed.
Signature
public Decimal stripTrailingZeros()
Return Value
Type: Decimal
Example
1Decimal myDecimal = 1.10000;
2Decimal stripped = myDecimal.stripTrailingZeros();
3System.assertEquals(stripped, 1.1);toPlainString()
Returns the String value of this Decimal, without using
scientific notation.
Signature
public String toPlainString()
Return Value
Type: String
Example
1Decimal myDecimal = 12345.6789;
2System.assertEquals('12345.6789', myDecimal.toPlainString());valueOf(doubleToDecimal)
Returns a Decimal that contains the value of the specified
Double.
Signature
public static Decimal valueOf(Double doubleToDecimal)
Parameters
- doubleToDecimal
- Type: Double
Return Value
Type: Decimal
Example
1Double myDouble = 2.718281828459045;
2Decimal myDecimal = Decimal.valueOf(myDouble);
3System.assertEquals(2.718281828459045, myDecimal);valueOf(longToDecimal)
Returns a Decimal that contains the value of the specified
Long.
Signature
public static Decimal valueOf(Long longToDecimal)
Parameters
- longToDecimal
- Type: Long
Return Value
Type: Decimal
Example
1Long myLong = 299792458;
2Decimal myDecimal = Decimal.valueOf(myLong);
3System.assertEquals(299792458, myDecimal);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.
Signature
public static Decimal valueOf(String stringToDecimal)
Parameters
- stringToDecimal
- Type: String
Return Value
Type: Decimal
Example
1String temp = '12.4567';
2Decimal myDecimal = Decimal.valueOf(temp);