Force.com Apex Code Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Decimal Class

Contains methods for the Decimal primitive data type.

Namespace

System

Usage

For more information on Decimal, see Primitive Data Types.

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:
  • 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
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
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
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: -2
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
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
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, an Exception is thrown. For example:
  • Input number 5.5: UNNECESSARY round mode result: Exception
  • Input number 1.0: UNNECESSARY round mode result: 1
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

Decimal Methods

The following are methods for Decimal.

abs()

Returns the absolute value of the Decimal.

Signature

public Decimal abs()

Return Value

Type: Decimal

divide(Decimal, Integer)

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)

Parameters

divisor
Type: Decimal
scale
Type: Integer

Return Value

Type: Decimal

Example

In the following example, D has the value of 0.190.

1Decimal D = 19;
2
3D.Divide(100, 3);

divide(Decimal, Integer, Object)

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, Object roundingMode)

Parameters

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

Return Value

Type: Decimal

Example

1Decimal myDecimal = 12.4567;
2
3Decimal divDec = myDecimal.divide
4
5   (7, 2, System.RoundingMode.UP);
6
7system.assertEquals(divDec, 1.78);

doubleValue()

Returns the Double value of this Decimal.

Signature

public Double doubleValue()

Return Value

Type: Double

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.

intValue()

Returns the Integer value of this Decimal.

Signature

public Integer intValue()

Return Value

Type: Integer

longValue()

Returns the Long value of this Decimal.

Signature

public Long longValue()

Return Value

Type: Long

pow(Integer)

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;
2
3Decimal powDec = myDecimal.pow(2);
4
5system.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(System.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

setScale(Integer)

Sets the scale of the Decimal to the given number of decimal places, using half-even rounding, if necessary. Half-even rounding mode rounds towards the “nearest neighbor” unless both neighbors are equidistant, in which case, this mode rounds towards the even neighbor.

Signature

public Decimal setScale(Integer scale)

Parameters

scale
Type: Integer
The value of scale must be between –33 and 33.

Return Value

Type: Decimal

Usage

If you do not explicitly set the scale for a Decimal, the scale is determined by the item from which the Decimal is created:
  • 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 scale is determined by converting the number to a String and then using the number of characters after the decimal point.

setScale(Integer, System.RoundingMode)

Sets the scale of the Decimal to the given number of decimal places, using the rounding mode specified by the rounding mode, if necessary.

Signature

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

Parameters

scale
Type: Integer
The value of scale must be between -32,768 and 32,767.
roundingMode
Type: System.RoundingMode

Return Value

Type: Decimal

Usage

If you do not explicitly set the scale for a Decimal, the scale is determined by the item from which the Decimal is created:
  • 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 scale is determined by converting the number to a String and then 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

toPlainString()

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

Signature

public String toPlainString()

Return Value

Type: String

valueOf(Double)

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

Signature

public static Decimal valueOf(Double convertToDecimal)

Parameters

convertToDecimal
Type: Double

Return Value

Type: Decimal

valueOf(Long)

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

Signature

public static Decimal valueOf(Long convertToDecimal)

Parameters

convertToDecimal
Type: Long

Return Value

Type: Decimal

valueOf(String)

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 convertToDecimal)

Parameters

convertToDecimal
Type: String

Return Value

Type: Decimal

Example

1String temp = '12.4567';
2
3Decimal myDecimal = decimal.valueOf(temp);