Component bdldfp_decimalimputil [Package bdldfp]

Provide a unified low-level interface for decimal floating point. More...

Namespaces
namespace	bdldfp

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Constructing a Representation of a Value in Decimal
    • Example 2: Adding Two Decimal Floating Point Values

Purpose:

Provide a unified low-level interface for decimal floating point.

Classes:

bdldfp::DecimalImpUtil

Unified low-level decimal floating point functions.

See also:

Component bdldfp_decimalimputil_inteldfp

Description:

This component provides a namespace, bdldfp::DecimalImpUtil, containing primitive utilities used in the implementation of a decimal floating point type (e.g., see bdldfp_decimal).

Usage:

This section shows the intended use of this component.

Example 1: Constructing a Representation of a Value in Decimal:

A common requirement for decimal floating point types is to be able to create a value from independent "coefficient" and "exponent" values, where the resulting decimal has the value coefficient * 10 ^ exponent. In the following example we use such a coefficient and exponent to create Decimal32, Decimal64, and Decimal128 values.

First we define values representing the coefficient and exponent (note the result should be the value 42.5):

  int coefficient = 425; // Yet another name for significand
  int exponent    =  -1;

Then we call makeDecimal32, makeDecimal64, and makeDecimal128 to construct a Decimal32, Decimal64, and Decimal128 respectively.

  bdldfp::DecimalImpUtil::ValueType32  d32 =
            bdldfp::DecimalImpUtil::makeDecimalRaw32( coefficient, exponent);
  bdldfp::DecimalImpUtil::ValueType64  d64 =
            bdldfp::DecimalImpUtil::makeDecimalRaw64( coefficient, exponent);
  bdldfp::DecimalImpUtil::ValueType128 d128 =
            bdldfp::DecimalImpUtil::makeDecimalRaw128(coefficient, exponent);

  ASSERT(bdldfp::DecimalImpUtil::equal(
                    bdldfp::DecimalImpUtil::binaryToDecimal32( 42.5), d32));
  ASSERT(bdldfp::DecimalImpUtil::equal(
                    bdldfp::DecimalImpUtil::binaryToDecimal64( 42.5), d64));
  ASSERT(bdldfp::DecimalImpUtil::equal(
                    bdldfp::DecimalImpUtil::binaryToDecimal128(42.5), d128));

Example 2: Adding Two Decimal Floating Point Values:

Decimal floating point values are frequently used in arithmetic computations where the precise representation of decimal values is of paramount importance (for example, financial calculations, as currency is typically denominated in base-10 decimal values). In the following example we demonstrate computing the sum of a sequence of security prices, where each price is held in a DecimalImpUtil::ValueType64 value.

First, we define the signature of a function that computes the sum of an array of security prices, and returns that sum as a decimal floating point value:

  bdldfp::DecimalImpUtil::ValueType64
  totalSecurities(bdldfp::DecimalImpUtil::ValueType64 *prices,
                  int                                  numPrices)
      // Return a Decimal Floating Point number representing the arithmetic
      // total of the values specified by 'prices' and 'numPrices'.
  {

Then, we create a local variable to hold the intermediate sum, and set it to 0:

      bdldfp::DecimalImpUtil::ValueType64 total;
      total = bdldfp::DecimalImpUtil::int32ToDecimal64(0);

Next, we loop over the array of prices and add each price to the intermediate total:

      for (int i = 0; i < numPrices; ++i) {
          total = bdldfp::DecimalImpUtil::add(total, prices[i]);
      }

Now, we return the computed total value of the securities:

      return total;
  }

Notice that add is called as a function, and is not an operator overload for +; this is because the bdldfp::DecimalImpUtil utility is intended to be used in the implementation of operator overloads on a more full fledged type.

Finally, we call the function with some sample data, and check the result:

  bdldfp::DecimalImpUtil::ValueType64 data[16];

  for (int i = 0; i < 16; ++i) {
      data[i] = bdldfp::DecimalImpUtil::int32ToDecimal64(i + 1);
  }

  bdldfp::DecimalImpUtil::ValueType64 result;
  result = totalSecurities(data, 16);

  bdldfp::DecimalImpUtil::ValueType64 expected;

  expected = bdldfp::DecimalImpUtil::int32ToDecimal64(16);

  // Totals of values from 1 to 'x' are '(x * x + x) / 2':

  expected = bdldfp::DecimalImpUtil::add(
               bdldfp::DecimalImpUtil::multiply(expected, expected),
               expected);
  expected = bdldfp::DecimalImpUtil::divide(
                       expected,
                       bdldfp::DecimalImpUtil::int32ToDecimal64(2));

  assert(bdldfp::DecimalImpUtil::equal(expected, result));

Notice that arithmetic is unwieldy and hard to visualize. This is by design, as the DecimalImpUtil and subordinate components are not intended for public consumption, or direct use in decimal arithmetic.