BigDecimals for Delphi

An up-to-date version of this and other files can be found in my DelphiBigNumbers project on GitHub.

BigDecimals

Ten decimal places of π are sufficient to give the circumference of the earth to a fraction of an inch, and thirty decimal places would give the circumference of the visible universe to a quantity imperceptible to the most powerful microscope. — Simon Newcomb

Floating point arithmetic can be very useful for non-integer calculations. The fact that they are hardware supported makes them fast, but due to the fact that the currently usual IEEE-754 types Single (binary32) and Double (binary64) are not only limited in size, they are also limited in precision and range.

Despite the statement in the quote above, sometimes a very high precision is needed. One example are certain financial calculations. The exact calculation of annual rates might require a precision of as much as 2191 digits, as described on this website. The exact calculation of certain physical or mathematical constants like π or e might even require a much higher precision.

I already implemented something every Delphi user should have at their disposal, BigIntegers, and now I also implemented the logical next step: BigDecimals. They are multi-precision, decimal floating point types. A few years ago, I implemented a Delphi version of the .NET-compatible Decimal type. BigDecimal is the big version of that, with an almost unlimited precision and almost unlimited range.

BigDecimal has a range that can vary between -536,870,912 and +536,870,912, so the tiniest value that can be represented is 1 × 10^-536,870,912 and the largest is at least 999999… × 10^+536,870,911. The precision is around 10^{5,000,000,000}.

Usage

BigDecimals are easy to use. They are value types, so you don’t have to worry about memory management. They can be used like:

var
  A, B, C: BigDecimal;
begin
  A := '1.3456e-17';        // exact
  B := 1234.197;            // floating point approximation
  C := A + B * '3.0';
  Writeln(string(C));

While you can use a BigDecimal like a simple floating point type, you should note that their real memory consumption can be much higher. A BigDecimal only consists of a pointer and a few integers, so on your stack it won’t take up much memory, but the value it represents is allocated on the heap, and that can be many more bytes, depending on the precision of the number that is represented.

BigDecimals are immutable, so any expression or public function that modifies the value returns a new BigDecimal. The original is not modified.

Initialization

There are several ways to get values into a BigDecimal. You can use constructors, like

A := BigDecimal.Create(1.79e308);        // floating point value
B := BigDecimal.Create('1.79e308');      // string (exact)

or (implicit or explicit) conversion operators like

B := '3.141592653589793238462643383279'; // string
C := -17;                                // integral type
E := BigDecimal(6.345E-30);              // floating point type

Constructors

Although BigDecimal is a record type and record constructors are no real constructors, and the syntax used can deceive you into thinking a new instance is allocated somewhere, I think records should have them, for initialization. But note that, if A is a BigDecimal, it doesn’t matter if you do:

A := BigDecimal.Create('1.7');

Or just:

A.Create('1.7');

Both will do exactly the same and initialize A with the value 1.7.

The constructors defined are:

MyBigDecimal := BigDecimal.Create(1.7);

MyBigDecimal := BigDecimal.Create('1.7');

Implicit conversions and class functions

The following implicit conversion operators are defined. Implicit means that you don’t have to cast, but can, if you want to. So you can either do:

  MyBigDecimal := BigDecimal('3.141592');

or you can do:

  MyBigDecimal := '3.141592';

and the result will be exactly the same.

The string parameter can have the same contents as a floating point literal, i.e. it consists mainly of decimal digits (‘0’..‘9’), it can have at most one decimal separator (‘.’), it can have one or more thousand separators (‘,’, or, alternatively, ’ ‘), an exponent part, consisting of an ’e’ or ‘E’, an optional sign (‘-’ or ‘+’), and an exponent consisting of decimal digits. The thousand separators can be anywhere. They are simply ignored.

Examples of valid strings are ‘1’, ‘1.034’, ‘1,000,000.345’, ‘1.79e308’ and ‘3,456,456.4e-13’. But also ‘1,,,2,,3.4e-99’, which is simply interpreted as ‘123.4e-99’.

Note, however, that trailing zeroes matter. So, while ‘1.00’ and ‘1.0000’ will compare as equal, they are different values. One has two, the other has four decimals, and BigDecimal remembers that. How this is done is explained later on (but know that the former is stored as 100 × 10^-2 while the latter is stored as 10,000 × 10^-4, so they have different internal representations).

Internals

Before I continue with the other methods and operators, I first want to talk a little about the internals.

A BigDecimal is a record type with only a few member fields. One is a BigInteger, which contains the significant digits of the BigDecimal. This is also called the unscaled value (internal field FValue). The other important member field is the scale (internal field FScale), which determines the power of 10 by which the unscaled value must be divided to get the nominal value of the BigDecimal. This means that a value like 1.79 is stored as an unscaled value of 179 and a scale of 2. In other words, the value is stored as 179 / 10² (which can also be seen as 179 × 10^-2). As you see, a positive scale means dividing by a power of 10. But, unlike in my Decimal type, the scale can be negative too, and then you multiply by a power of 10. So 1.79e+308 is stored as an unscaled value of 179 too, but now with a scale of -306.

For what it’s worth, in many programming languages, including Delphi, 1.79e30 or 1.79e+30 are the usual source code representations of the floating point number 1.79 × 10³⁰. E or e stand for “exponent”. Likewise, 3.45e-8 stands for 3.45 × 10⁻⁸ (or 0.0000000345).

The usage of a scale allows BigDecimals to have the same nominal values but different precisions. As I said before, 1.00 and 1.0000 compare both as exactly 1, but the former has a precision of 3, while the latter has a precision of 5 digits. The former is stored as 100 / 10², while the latter is stored as 10000 / 10⁴.

The sign of the BigDecimal is simply the sign of the contained BigInteger.

Since BigInteger already knows how to add, subtract, multiply or divide, these operations are done by the BigIntegers. This does not mean that you can simply add two values with different scales. The scale must be adjusted to the larger of the two (by multiplying the BigInteger of the BigDecimal with the smallest scale by a power of 10 and adjusting the scale accordingly). Multiplication is similar: the BigIntegers are multiplied and the scales are added. Division is a little more difficult. You can’t simply divide the BigIntegers, because 1 div 3 returns 0, and you want something like 0.3333333…. That is where precision comes into play. The dividend is first multiplied by 10^precision, then it is divided by the divisor and the result is then rounded towards the target scale as much as possible. The target scale is the difference between dividend.Scale and divisor.Scale. How the rounding is done depends on the rounding mode.

Rounding and precision

First, let’s define precision as it is used here. Precision is the number of decimal digits the unscaled value (i.e. the BigInteger) represents. This is equivalent to:

Precision := System.Math.Ceil(UnscaledValue.BitLength * Ln(2) / Ln(10));
if Precision = 0 then
  Precision := 1;

where BitLength * Ln(2) / Ln(10) is equivalent to Log10(N). If the BigInteger is 0, then the result of the first line is 0 too, but that is seen as a precision of 1 anyway. So the precision of 1.79e+308 is only 3, not 308, because the BigInteger is 179 and that has only three digits.

Rounding is cutting off the least significant digits of a value to obtain a number with a lower precision. If the precision you need is higher than the current precison, you simply multiply the unscaled value by the necessary power of 10 and adjust the scale accordingly. No rounding is required. But if the required precision is lower, you must cut off digits at the right and sometimes, you must adjust the unscaled value to do the required rounding.

BigDecimal defines an enumeration type RoundingMode, which governs how values are rounded, for instance after a division. It can can have the following values:

MathContext mc = new MathContext(20, RoundingMode.HALF_DOWN); // precision, rounding mode
BigDecimal monthly = total.add(fixed).divide(BigDecimal.valueOf(12), mc);
BigDecimal additional = monthly.multiply(BigDecimal.valueOf("1.19")).add(BigDecimal.valueOf("3.2"));

  BigDecimal.DefaultPrecision := 20;
  BigDecimal.DefaultRoundingMode := rmNearestDown;

  Monthly := (Total + Fixed) / 12;
  Additional := Monthly * 1.19 + 3.2;

Back to Usage

Mathematical operations

A type like this is of no use if you can’t calculate with it. BigDecimal defines the usual mathematical operators +, -, * and /. But it also defines div and mod. Of those two, the former returns an integral division result, the latter the remainder after that division. These operators have corresponding class functions as well, and the overloaded versions of these take rounding mode and precision parameters too. Here’s a table:

Comparison operations

All comparison operations base on the Compare function. Here they are:

Just like in mathematics, Compare compares two values with different scale but same nominal value as equal, so

  X := BigDecimal.Compare('1.10', '1.1000');

returns 0, meaning equality. In the same sense,

  Y := BigDecimal('-1.2300') < BigDecimal('-1.23');

returns False.

In Java, if two BigDecimals have the same nominal value, but different scales, the equals() function returns false. And if you use ==, they must even be identical, i.e. have the same reference (address). To compare the numerical value of two BigDecimals, let’s call them a and b, you must do something like areTheyEqual = (a.compareTo(b) == 0);. This is not necessary for the Delphi BigDecimals described here. You can simply use = to compare two BigDecimals for numerical equality, even if they have different scales.

Explicit conversions

Explicit conversions were made to be silent, so if this is possible, they don’t raise exceptions. In the following piece of code (without BigDecimals):

var
  I64: Int64;
  I32: Integer;
begin
  I64 := -10000000000000;
  I32 := Integer(I64);

I32 ends up with a value of -1316134912, because that is the value of the low 32 bit part of the Int64. The same principle applies to BigDecimal, so instead of raising an exception because the value in the BigDecimal does not fit in the target type, a silent conversion is performed that makes it fit.

String conversion

There are a few routines for conversion to and from a string. A valid string is like a valid floating point literal:

• an optional sign (‘+’ or ‘-’)
• a significand, consisting of
  • an integral part, consisting of one or more decimal digits (‘0’..‘9’)
  • an optional decimal point
  • an optional fractional part, consisting of one or more decimal digits
  • optional thousands separators or spaces — these are ignored
• an optional exponent, consisting of
  • an exponent delimiter, either ‘e’ or ‘E’
  • an optional sign (‘+’ or ‘-’)
  • an exponent value, consisting of one or more decimal digits

Here are a few examples of valid (locale invariant) strings representing a BigDecimal:

Parsing

There are four routines for parsing a string into a BigDecimal. Two use the invariant format settings, where ‘.’ is the decimal separator and ‘,’ is the thousands separator. The other two use explicit TFormatSettings parameters, e.g. for Germany, where I live, I could use TFormatSettings.Create(‘de_DE’).

Conversion to string

There are four routines that convert a BigDecimal to a string. The routines ToString generally return the shortest possible string representation. If necessary, the value is represented in scientific notation, i.e. with an exponent. So 1.79e30 is represented as ‘1.79e30’. The routines ToPlainString always use the plain notation and don’t use scientific. This means that a value of 1.79e30 is represented as ‘1790000000000000000000000000000’. But note that both representations do not lose precision, so if the precision requires thirty decimals, even ToString will represent all of them. An example:

var
  D1, D2: BigDecimal;
begin
  D1 := '1.7900000000000000000000e30'; // note: 20 trailing zeros
  D2 := '1.79e30';
  Writeln(Format('D1 = %s, D2 = %s', [D1.ToString, D2.ToString]));
  Writeln(Format('D1 = %s, D2 = %s', [D1.ToPlainString, D2.ToPlainString]));
end;

The output is

D1 = 1.7900000000000000000000e+30, D2 = 1.79e+30
D1 = 1790000000000000000000000000000, D2 = 1790000000000000000000000000000

In other words, ‘1.7900000000000000000000e+30’ is the shortest representation D1.ToString can generate, because the trailing zeros are part of the precision and they can not be cut off.

There is a way to cut off the trailing zeros of a BigDecimal, using RemoveTrailingZeros. This is discussed later on.

Miscellaneous functions

There are a number of functions that return information about a BigDecimal, or return modified versions of the original BigDecimal.

Rounding and scaling

Rounding and scaling are closely related. Scaling down often requires rounding. The following functions return rounded or truncated versions of the original values.

Information

The following instance methods return information about the current BigDecimal.

Properties

Predefined BigDecimals

The unit defines a few useful constants for often needed BigDecimal values. These should be used preferrably to newly created BigDecimals with the same values. That avoids duplication of the payload of the contained BigInteger.

System-wide defaults

Beside the already mentioned defaults for precision and rounding mode, there is also a default for the exponent delimiter used in string output. The default is ‘e’ and not, as in most other implementations, ‘E’, because to me, a lower case letter between digits that generally have the height of upper case letters, is more clearly visible than an upper case ‘E’. In other words, I prefer ‘1.798765432102345e+30’ over ‘1.798765432102345E+30’, because I find it more readable.

Access to internals

The fields of a BigDecimal can be accessed read-only:

A negative scale my be a little hard to understand. Note that 1e+3, which has a precision of 1, will be represented by an UnscaledValue of 1, but to make it get the value of 1 × 10³, the scale will have to be set to -3. Mathematically, that is the same as 1000, but internally, it isn’t. That is because 1e+3 has a precision of 1, while 1000 has a precision of 4.

Visualizer

Since I had to write a simple parser for the debugger visualizer for BigInteger anyway, I amended it to parse debug output for BigDecimal too, so now there is a debugger visualizer for both BigInteger and BigDecimal, in the same unit. See here how to get and install it.

Notes

FPrecision

Currently, there is a private FPrecision instance field. This is meant to serve as a cache for the Precision function. BigDecimals are immutable, so the value of the record never changes. The idea is that if FPrecision is 0, it is uninitialized and the Precision function must calculate the precision. But once that is done, it can’t change, so it could be stored in FPrecision and the function could return this cached value. The problem is, however, that unlike classes, records are not zeroed out on automatic initialization. So if, in the Precision function, I read a value that is not 0, I can’t be sure if it was calculated before, or if it is garbage resulting from previous use of the memory. All routines that initialize or modify the internals of a new BigDecimal currently initialize FPrecision to 0, but the uncertainty remains.

On the other hand, if you use an Integer or a Double without initializing it, you get garbage and undefined behaviour too. So I could blame undefined values of FPrecision on the same undefined behaviour you get when you don’t initialize variables of the built-in types and simply use FPrecision as it was intended.

Mathematics

Currently, there are no functions that provide higher mathematical functions (except Sqrt) for BigDecimals. I intend to write a new unit that provides functions like Cos, ArcTan, SinH, Ln, Exp or Pi with a set precision, but that is still in the planning stage. Such functions will probably be extremely slow, compared to hardware supported floating point, but much more accurate.

Number formatter

I also plan to implement a unit that provides a general number formatter. To this, you pass a record containing a string of digits, a scale and some more information, and it uses a format string like ‘#,##000.e+000’, more or less like Delphi’s FloatToStr does, to format the output. I intend to make it able to format the built-in floating point types, my Decimal type and my BigDecimal type by default, but it should also be able to format other types, if you can pass the data in the required record.

Conclusion

I hope this code is useful to you. If you use some of it, please credit me. If you modify or improve the unit, please send me the modifications at this e-mail address.

I may improve or enhance the unit myself, and I will try to post changes here. But this is not a promise. Please don’t request features.

Rudy Velthuis