*EDA *
Eiffel Decimal Arithmetic - User Guide

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.

${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 ...

- 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.

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.

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

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.

- 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

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.

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.

- 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.

**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.

- 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*.

- 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.

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

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

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

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

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

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

- PLATFORMS
- Should run on any platform.
- COMPILERS
- Any GOBO supported Eiffel compiler.

- Create an application
- Create a XACE project definition, and mount the ${GOBO}/library/math/decimal/library.xace
- Create a 'build.eant' file.

- Generate the application : Automate build with geant.

EDA has currently been tested using

- ESI EiffelStudio 5.2, 5.3, 5.4 (Win32, Linux)
- SmartEiffel 1.0, 1.1 (Win32, Linux),
- Visual Eiffel v4.1 (Win32, Linux)

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

- 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.