Content

  1. Introduction
  2. Concepts
  3. Classes
  4. Usage
  5. Installation
  6. Reference documents

Introduction

Floating point arithmetic using binary representation does not meet requirements of many application fields like accounting, legal, tax, and more. Many programmers experienced problems using binary floating point arithmetic : loss of accurracy, problems of inexact representation, etc...

Existing databases store a lot of data using decimal representation. Unfortunately, not many languages support decimal arithmetic natively. What's the use of storing decimal data if arithmetic operations do not support this representation?

Thanks to the excellent specification work of Mike Cowlishaw, IBM Fellow, it is now possible to develop a standards-compliant decimal arithmetic library.

EDA is an Eiffel implementation of the "General Decimal Arithmetic Specification" (GDAS, in the rest of this text) version 1.08 (see References, 1).

By following the GDAS, this Eiffel implementation conforms to the requirements of the ANSI/IEEE standard 854-1987, while supporting integer and unrounded floating-point arithmetic as a subset (see GDAS page 1). EDA uses the acceptance tests of IBM, so that the implementation can be trusted.

EDA has been incorporated in the acclaimed GOBO library since 2004.

Content of the package

${GOBO}
   |
   + doc
   |   + math
   |      + decimal             -- index.html
   |
   + example
   |   + math
   |      + decimal
   |         + telco            -- Telco benchmark application

   ...

   + library
   |   + math
   |      + decimal
   |         + abstract
   |         + implementation
   |         + spec

   ...

   + test
   |   + math
   |      + decimal
   |         + acceptance       -- Acceptance/non-regression tests using IBM's test cases
   ...

GDAS Standard conformance

Arithmetic operations
abs, add and subtract, compare, divide, divide-integer, max, min, minus, plus, multiply, normalize, remainder, rescale, round-to-integer.
Conversion
to_scientific_string, to_engineering_string, to_number (as creation routine 'make_from_string').
Context
7 rounding modes : Round_up, Round_down, Round_ceiling, Round_floor, Round_half_up, Round_half_down, Round_half_even.
Not Implemented
remainder-near, square-root, power.

Acknowledgements

Special thanks to Mike Cowlishaw for his work on decimal arithmetic and for the help he provided, answering promptly to many questions. He helped understand the specification. He also helped clarify problems when running the test cases.

Concepts

Users who want to get the most of this library, should have read thoroughly the GDAS specification.

Decimal numbers

Decimal numbers can be finite or special.

A finite number has the following characteristics :

sign
positive or negative
coefficient
a sequence of digits (0 through 9). This sequence represents a positive integer number, and may not be empty.
exponent
a signed integer. This is the power of ten by which the coefficient is multiplied.

Finite numbers can be represented by a triad [sign, coefficient, exponent] that fully represent a number.
[0, 2708, -2] represents 27.08;
[1, 1289, 0] represents -1289.

Special numbers are :

Infinity
A value whose magnitude is infinitely large. It may be positive or negative.
quiet NaN
Undefined result ("Not a Number"), which shall not raise an Invalid operation signal.
signaling NaN
Undefined result, which shall raise an Invalid operation signal.

Special numbers can be represented by a diad [sign, symbol] : [1, Inf] is -Infinity; [0, Inf] is +Infinity ; [0, qNaN] is quiet NaN ; [0, sNaN] is signaling NaN.

Operations

Conversions
conversion to numeric string in scientific or engineering format : to-scientific-string, to-engineering-string; creation of number from another type : from-integer, from-double, from-string
Arithmetic operations
abs, add, subtract, compare, divide, divide-integer, max,min, minus, plus, multiply, normalize, remainder, rescale, round-to-integer

Mathematical context

Nearly all the operations are relative to a mathematical context. A context is the set of parameters and rules which govern the results of arithmetic operations. Those parameters and rules are user-selectable. The next sections contain extracts from the GDAS document.

Digits
also know as precision. Maximum number of significant digits that can results from arithmetic operations.
Rounding mode
Algorithm to be used when rounding is necessary, i.e. when a result value has more significant digits than digits.
Flags
Flags that represent exceptional conditions. A raised flag is known as a signal.
Traps
A trap can be enabled or disabled. There are as many traps as there are exceptional conditions. An enabled trap raises an exception when the corresponding signal occurs.

Rounding modes

When a result value has more significant digits than digits, the digits in excess are discarded with respect to the rounding mode.

round-down
Truncate : just drop the digits in excess.
round-half-up
If the discarded digits represent greater than or equal to half (0.5) of the value of a one in the next left position then the result should be incremented by 1 (rounded up).
round-half-even
If the discarded digits represent greater than half (0.5) the value of a one in the next left position then the result should be incremented by 1 (rounded up). If they represent less than half, then the result is not adjusted (that is, the discarded digits are ignored). Otherwise (they represent exactly half) the result is unaltered if its rightmost digit is even, or incremented by 1 (rounded up) if its rightmost digit is odd (to make an even digit).
round-ceiling
Round toward +Infinity. If all of the discarded digits are zero or if the sign is negative the result is unchanged. Otherwise, the result should be incremented by 1 (rounded up). If this would cause overflow then the result will be +Infinity.
round-floor
Round toward -Infinity. If all of the discarded digits are zero or if the sign is positive the result is unchanged. Otherwise, the sign is 1 and the coefficient should be incremented by 1. If this would cause overflow then the result will be -Infinity.
round-half-down
Round to nearest, where a 0.5 case is rounded down.
round-up
Round away from zero.

Signals - Exceptional conditions

SIGNAL
RAISED WHEN ...
division-by-zero
Non-zero dividend is divided by zero.
inexact
Result is not exact (one or more non-zero coefficient digits were discarded during rounding).
invalid-operation
Result would be undefined or impossible.
overflow
The exponent of a result is too large to be represented.
rounded
Result has been rounded (that is, some zero or non-zero coefficient digits were discarded).
subnormal
Result is subnormal (its adjusted exponent is less than Emin), before any rounding.
underflow
Result is both subnormal and inexact.

Classes

Class
Description
MA_DECIMAL
Decimal numbers whoses operations are specified by GDAS.
MA_DECIMAL_CONTEXT
Mathematical contexts that hold status flags and various control options like current rounding mode.
MA_SHARED_DECIMAL_CONTEXT
Objects that give access to a single, shared, decimal context. Decimal operations whose signature do not use an explicit context do use this shared context.

MA_DECIMAL

sign
+1 positive, -1 negative.
exponent
Power of ten by which the (invisible) coefficient is multiplied.
+, -, *, /, //, \\
Infix operations using shared_decimal_context : add, subract, multiply, divide, divide-integer, remainder respectively.
+, -
Prefix operations using shared_decimal_context : plus, minus respectively.
is_nan, is_quiet_nan,
is_signaling_nan
NaN indicators.
is_infinity
Infinity indicator.
is_special
Special value indicator.
is_zero
Zero indicator - shortcut to avoid comparing with zero.
to_double,
to_integer,
to_scientific_string,
to_engineering_string
Conversion to integer, double, and string representations.
add, subract,
multiply, divide,
divide_integer, remainder
Operations using an explicit context.
rescale
rescale to specific exponent.
normalize
normalize internal representation.
abs, min, max
abs, min, max relative to implicit shared_decimal_context
abs_ctx, min_ctx, max_ctx
abs, min, max using explicit context
compare
three way comparison using explicit context
<, >, <=, >=
Comparison infix operators using implicit shared_decimal_context.

MA_DECIMAL_CONTEXT

digits
maximum number of significant digits.
rouding_mode
integer value specifying the rounding algorithm to be used.
set_digits
digits setter.
set_rounding_mode
rouding_mode setter.
is_flagged (signal)
Status of signal : is it raised (flagged) ?
is_trapped (signal)
Is signal trapped ?
exception_on_trap
Is an exception raised when a trap occurs.
is_extended
Is the context extended?

Signals are flagged when they occur. If the signal is trapped, then an exception is raised if exception_on_trap is True.

MA_SHARED_DECIMAL_CONTEXT

Features

shared_decimal_context
decimal context implicitly used by various operations.
set_shared_decimal_context
sets the current shared decimal context.
decimal_zero
Constant zero : neutral element for addition.
decimal_one
Constant one : neutral element for multiplication.

The default decimal context has the following characteristics : digits = 9, rounding_mode = round_half_up,
is_trapped (Signal_division_by_zero), is_trapped (Signal_invalid_operation),is_trapped (Signal_overflow), is_trapped (Signal_underflow).

Usage

Local Definitions for the code

	a, b, c, d, r : MA_DECIMAL
	ctx, dbl_ctx : MA_DECIMAL_CONTEXT

Creation

	--| using a default decimal context for general purpose arithmetic (IEEE 854),
	create a.make_from_integer (4)
	create b.make_from_string ("314e-2")

	--| using an explicit double precision decimal context
	create ctx.make_double
	create a.make_from_string_ctx ("3.141598", ctx)

Basic Operations

	create dbl_ctx.make_double

	--| using explicit context
	a := a.multiply (b, dbl_ctx)

	--| using implicit shared decimal context
	--| set desired context first
	set_shared_decimal_context (dbl_ctx)

	r := a * b + c \\ d

Code fragment using shared context and infix operations

--| establish math contexts
create price_context.make_double
price_context.set_digits (31)
price_context.set_rounding_mode (price_context.Round_half_even)
tax_context := price_context.cloned_object
tax_context.set_rounding_mode (tax_context.Round_down)
create default_context.make_double
default_context.set_digits (31)

...

--| 1. Price
set_shared_decimal_context (default_context)
if long_distance then
	price := number * distance_rate
	long_distance_count := long_distance_count + 1
else
	price := number * base_rate
end
price := price.rescale (-2, price_context)
if tax then
	--| 2. Basic tax
	set_shared_decimal_context (tax_context)
	base_tax := price * base_tax_rate
	base_tax := base_tax.rescale (-2, tax_context)
	sum_b := sum_b + base_tax
	total_price := price + base_tax
	--| 3. Long distance calls
	if long_distance then
		distance_tax := price * distance_tax_rate
		distance_tax := distance_tax.rescale (-2, tax_context)
		sum_d := sum_d + distance_tax
		--| 4. total price
		total_price := total_price + distance_tax
	end
else
	total_price := price
end

Conversion

	print ("Scientific representation : ")
	print (a.to_scientific_string)

	print ("Engineering representation : ")
	print (b.to_engineering_string)

With a = b = [1,123,-12], the output is

Scientific representation : -1.23e-10
Engineering representation : -123e-12

Installation

PLATFORMS
Should run on any platform.
COMPILERS
Any GOBO supported Eiffel compiler.
  1. Create an application
    • Create a XACE project definition, and mount the ${GOBO}/library/math/decimal/library.xace
    • Create a 'build.eant' file.
  2. Generate the application : Automate build with geant.

EDA has currently been tested using

.NET acceptance tests have no errors but MA_DECIMAL_CONTEXT flags for comparison operations are not set correctly.

Reference Documents

1. GDA Specification
"General Decimal Arithmetic Specification" version 1.08, Mike Cowlishaw, IBM UK Laboratories.
2. GOBO Library
http://sourceforge.net/projects/gobo-eiffel; http://www.gobosoft.com.
3. Decimal Arithmetic
"IBM's site dedicated to Decimal Arithmetic" : http://www2.hursley.ibm.com/decimal.
4. Acceptance Tests specification
IBM's acceptance tests specification documentation, whose version is in sync with GDAS 1.08.