Decimal encoding sample code

This sample code was devised to illustrate encoding of decimal floating-point numbers in binary bit strings, and corresponding decoding.

Please see the document "General Decimal Arithmetic" at http://www2.hursley.ibm.com/decimal for a full description of the encoding formats used. This sample code provides support for the Decimal32, Decimal64 and Decimal128 encodings defined in that document, which product 32-bit, 64-bit and 128-bit binary representations respectively.

This sample code provides a library of static methods to perform the various encoding and decoding operations. The principal entry points are the methods on the DecimalEncoder class and on the DecimalDecoder class. This sample code also includes some support classes for expressing floating-point numbers in a generic "model" form, and for expressing binary bit strings, and these are used as inputs to and outputs from a number of the encoding and decoding methods. For more details, see Java source files below.

This sample code is experimental, and may contain errors. It is offered on an as-is basis. In particular, this sample code is designed to be illustrative rather than to be an implementation optimised for any particular purpose. Indeed, a number of obvious optimisations are omitted in the interests of maximising clarity.

Package contents

In addition to this overview, the package contains the following subdirectories.

subdirectory description

src contains the Java source files for the sample code. For more details, see Java source files below.

lib contains a JAR file, decsample.jar, containing the classes defined in the Java source files. This JAR file may be included into a Java classpath in order to use the classes from other Java source.

doc contains the complete JavaDoc documentation for the sample code.

subdirectory	description
src	contains the Java source files for the sample code. For more details, see Java source files below.
lib	contains a JAR file, decsample.jar, containing the classes defined in the Java source files. This JAR file may be included into a Java classpath in order to use the classes from other Java source.
doc	contains the complete JavaDoc documentation for the sample code.

Java source files

The following Java source files contain "concrete" classes which are intended to be instantiated and used. Objects of these classes support the encoding and decoding methods.

source file description

com/ibm/eou/decimal/ArithmeticConditions.java This class provides a set of conditions that can arise during numeric conversions and arithmetic operations.

com/ibm/eou/decimal/BitString.java This class represents a field of binary bits, and provides some fundamental operations on them. Instances are delivered as the result of decimal encoding methods on the DecimalEncoder class, and may be supplied as parameters to decimal decoding methods on the DecimalDecoder class.

com/ibm/eou/decimal/ModelNumber.java This class represents a generic floating-point number, with almost no limitation on precision or magnitude, and also includes some special values. Finite numbers are represented as a sign, a finite-length coefficient expressed as a string of digits in a given radix, and a signed integer exponent. The coefficient length is limited only by storage, and the exponent is limited only to values which can be stored by a Java 'int' type. Infinities can also have a sign, and two not-a-number (NaN) values (quiet and signaling) are also supported.

source file	description
com/ibm/eou/decimal/ArithmeticConditions.java	This class provides a set of conditions that can arise during numeric conversions and arithmetic operations.
com/ibm/eou/decimal/BitString.java	This class represents a field of binary bits, and provides some fundamental operations on them. Instances are delivered as the result of decimal encoding methods on the DecimalEncoder class, and may be supplied as parameters to decimal decoding methods on the DecimalDecoder class.
com/ibm/eou/decimal/ModelNumber.java	This class represents a generic floating-point number, with almost no limitation on precision or magnitude, and also includes some special values. Finite numbers are represented as a sign, a finite-length coefficient expressed as a string of digits in a given radix, and a signed integer exponent. The coefficient length is limited only by storage, and the exponent is limited only to values which can be stored by a Java 'int' type. Infinities can also have a sign, and two not-a-number (NaN) values (quiet and signaling) are also supported.

The following Java source files contain classes which are never instantiated but which contain static methods which can be used to perform various encoding and decoding tasks.

source file description

com/ibm/eou/decimal/DecimalConstants.java This class provides static types and constants used by library methods on the DecimalEncoder class and the DecimalDecoder class for encoding and decoding binary representations of decimal floating-point numbers using the Decimal32, Decimal64 and Decimal128 formats.

com/ibm/eou/decimal/DecimalDecoder.java This class provides static library methods for interpreting and decoding binary representations of decimal floating-point numbers using the Decimal32, Decimal64 and Decimal128 formats.

com/ibm/eou/decimal/DecimalEncoder.java This class provides static library methods for encoding binary representations of decimal floating-point numbers using the Decimal32, Decimal64 and Decimal128 formats.

source file	description
com/ibm/eou/decimal/DecimalConstants.java	This class provides static types and constants used by library methods on the DecimalEncoder class and the DecimalDecoder class for encoding and decoding binary representations of decimal floating-point numbers using the Decimal32, Decimal64 and Decimal128 formats.
com/ibm/eou/decimal/DecimalDecoder.java	This class provides static library methods for interpreting and decoding binary representations of decimal floating-point numbers using the Decimal32, Decimal64 and Decimal128 formats.
com/ibm/eou/decimal/DecimalEncoder.java	This class provides static library methods for encoding binary representations of decimal floating-point numbers using the Decimal32, Decimal64 and Decimal128 formats.

For complete details of the methods for encoding and decoding decimal floating-point values, see the complete JavaDoc documentation for the package of sample code.

Please send any comments or corrections to Dave Clark, `dave_clark@uk.ibm.com`
Copyright © IBM Corporation 2003. All rights reserved. Java is a trademark of Sun Microsystems Inc.
[ IBM home page \| Search \| Contact IBM \| Help \| Legal \| Privacy ]