IEEE 754 decimal floating-point types for .NET: Decimal32, Decimal64, and Decimal128.
Written in C# with no native dependencies. Requires .NET 10.
Each value has a sign, an integer coefficient, and a base-ten exponent. Decimal fractions
such as 0.1 are stored exactly, so 0.1 + 0.2 equals 0.3. The exponent range covers
the full IEEE 754 range, including subnormals, infinities, and NaNs. This differs from
System.Decimal, which has a fixed scale and no special values.
using Decimals;
var price = Decimal64.Parse("19.99");
var quantity = Decimal64.Parse("3");
var total = price * quantity;
Console.WriteLine(total); // 59.97
Console.WriteLine(total / 7); // 8.567142857142857
Console.WriteLine(Decimal64.Sqrt(2)); // 1.414213562373095The arithmetic follows Mike Cowlishaw's General Decimal Arithmetic Specification, which became the decimal part of IEEE 754-2008 and IEEE 754-2019. The specification, the encodings, and the test suite are published at https://speleotrove.com/decimal/.
The reference implementation is decNumber, a C library by the same author
(https://speleotrove.com/decimal/#decNumber). It provides an arbitrary-precision engine
and three fixed-size types: decSingle, decDouble, and decQuad. The types in this
repository follow the fixed-size design. A value is a small struct, and the arithmetic
does not allocate.
Correctness is tested against decNumber's .decTest files. See Testing.
Some operations are renamed to follow .NET conventions. For example, to-number is
Parse, to-scientific-string is ToString, remainder-near is RemainderNear, and
or is Or.
Decimal32 |
Decimal64 |
Decimal128 |
|
|---|---|---|---|
| size | 4 bytes | 8 bytes | 16 bytes |
| precision | 7 digits | 16 digits | 34 digits |
| Emax | +96 | +384 | +6144 |
| Emin | -95 | -383 | -6143 |
| Etiny | -101 | -398 | -6176 |
| largest finite | 9.999999E+96 | 9.999999999999999E+384 | 9.999999999999999999999999999999999E+6144 |
| smallest subnormal | 1E-101 | 1E-398 | 1E-6176 |
A value equals (-1)^sign x coefficient x 10^exponent. The specification defines
decimal32 as a storage format only, and decNumber has no arithmetic for it. Decimal32
here supports the same arithmetic as the other two types.
Each format is a separate project (Decimal32/, Decimal64/, Decimal128/) with no
dependency on the others. Each has its own context, rounding, status, and class types,
for example Decimal64Context and Decimal64Rounding. The examples below use
Decimal64. The other two types have the same members.
var fromText = Decimal64.Parse("1.05");
var fromInt = (Decimal64)42; // implicit
var fromLong = (Decimal64)9223372036854775807L; // explicit, rounds to 16 digits
var widened = Decimal128.CreateChecked(fromText); // exact
var narrowed = Decimal32.CreateChecked(fromText); // may roundConversion from an integer type is implicit when every value of that type fits in the format's precision:
| format | implicit from |
|---|---|
Decimal32 |
sbyte, byte, short, ushort, char |
Decimal64 |
the above, plus int and uint |
Decimal128 |
the above, plus long and ulong |
Conversion from any other integer type is explicit. Conversion to an integer truncates
toward zero and throws OverflowException if the result does not fit.
There are no cast operators between the three formats, and none to or from
System.Decimal. Use CreateChecked, CreateSaturating, or CreateTruncating instead.
Converting to a wider decimal format is exact and keeps the exponent. Converting to a
narrower one rounds.
var shortest = (Decimal128)0.1; // 0.1
var exact = Decimal128.FromBinary(0.1, Decimal128BinaryConversion.ExactValue);
// 0.1000000000000000055511151231257827The cast operator uses the shortest decimal string that converts back to the same
double. For 0.1, that is 0.1.
FromBinary with ExactValue converts the exact binary value instead, rounded to the
format's precision. This is IEEE 754 convertFormat. Decimal128 shows the binary error
in 0.1 because it has 34 digits. Decimal64 gives 0.1000000000000000 because the
error is beyond its 16 digits.
Operators round half to even and do not report status. This is IEEE 754 default exception handling.
var sum = a + b;
var quotient = a / b;
var scaled = Decimal64.FusedMultiplyAdd(a, b, c); // one rounding
var root = Decimal64.Sqrt(a);
var power = Decimal64.Pow(a, b);Every operation has an overload that takes a context by reference. Use it to set the rounding mode or to read the status flags:
var context = new Decimal64Context(Decimal64Rounding.Ceiling);
var quotient = Decimal64.Divide(dividend, divisor, ref context);
if (context.HasRaised(Decimal64Status.Inexact))
{
// the result was rounded
}Rounding modes: Ceiling, Down, Floor, HalfDown, HalfEven, HalfUp, Up, and
ZeroFiveUp.
Status flags stay set until ClearStatus is called, so one check after a sequence of
operations reports everything raised during it. The flags are the five IEEE 754
exceptions (InvalidOperation, DivisionByZero, Overflow, Underflow, Inexact) and
the specification's additional conditions (ConversionSyntax, DivisionImpossible,
DivisionUndefined, Clamped, Rounded, Subnormal).
A value is stored as a coefficient and an exponent, and the same number can be stored in
more than one way. 1 is stored as coefficient 1 with exponent 0. 1.00 is stored as
coefficient 100 with exponent -2. Both equal one. The value of the last digit, 10 to the
power of the exponent, is called the quantum: 1 for 1, and 0.01 for 1.00.
The set of all encodings of one number is called a cohort. The type keeps the exponent, so the two members of this cohort behave differently in some operations:
var one = Decimal64.Parse("1"); // coefficient 1, exponent 0
var alsoOne = Decimal64.Parse("1.00"); // coefficient 100, exponent -2
one == alsoOne // true: the numbers are equal
one.Equals(alsoOne) // true
one.GetHashCode() == alsoOne.GetHashCode() // true
one.ToString() // "1"
alsoOne.ToString() // "1.00": the text shows the exponent
one.ToBits() == alsoOne.ToBits() // false: the stored coefficient and exponent differ
Decimal64.CompareTotal(one, alsoOne) // > 0: the total order puts 1.00 before 1==, Equals, GetHashCode, and CompareTo compare numeric value only. All members of a
cohort are therefore the same dictionary key and sort as equal. CompareTotal is the
IEEE 754 total order. It also compares exponents: for positive numbers in the same
cohort, the one with the smaller exponent comes first.
Each operation's result exponent is defined by the specification. For example,
1.20 + 0.30 is 1.50, and 1.2 * 1.5 is 1.80. Quantize sets the exponent
explicitly. Reduce and Trim remove trailing zeros.
var money = Decimal64.Quantize(total, Decimal64.Parse("0.01"), ref context); // two placesThe operators ==, !=, <, >, <=, and >= compare numeric value and follow
IEEE 754. Every comparison involving a NaN is false, except !=, which is true.
Equals, GetHashCode, and CompareTo follow .NET conventions instead. A NaN equals
another NaN and sorts before all other values. double works the same way, and this is
what allows the types to be used in collections.
CompareTotal and CompareTotalMagnitude implement the IEEE 754 total order, which
orders NaNs, signs, and cohort members. Compare and CompareSignal implement the
specification's comparison and return a decimal: -1, 0, 1, or NaN.
value.ToString() // scientific form
value.ToEngineeringString() // exponent is a multiple of three
value.ToString("F2", CultureInfo.InvariantCulture)
value.ToString("G", CultureInfo.GetCultureInfo("de-DE")) // 1234,5
Decimal64.Parse("1.05");
Decimal64.Parse("1.234,5", CultureInfo.GetCultureInfo("de-DE"));
Decimal64.TryParse("1.05"u8, out var fromUtf8); // UTF-8 inputMethods without an IFormatProvider use the specification's format. It does not depend
on CultureInfo.CurrentCulture. This applies to ToString(), ToScientificString,
ToEngineeringString, and Parse and TryParse without a provider. Note that this
differs from other .NET numeric types, where ToString() uses the current culture.
Methods with an IFormatProvider use that provider's separators, signs, and currency
symbols, and accept NumberStyles. The default style is Float | AllowThousands.
Infinity, sNaN, and NaN payloads are also accepted with a provider.
The "E" format specifier produces engineering notation, not .NET exponential notation.
var bits = value.ToBits(); // uint, ulong, or UInt128
var restored = Decimal64.FromBits(bits);
var binary = value.ToBidBits(); // BID, same as ToBits
var fromBinary = Decimal64.FromBidBits(binary);
var interchange = value.ToDpdBits(); // DPD
var fromWire = Decimal64.FromDpdBits(interchange);Values are stored in the BID (binary integer decimal) encoding, where the coefficient is
a binary integer. ToBits and ToBidBits return the stored bits. ToDpdBits and
FromDpdBits convert to and from the DPD (densely packed decimal) encoding, which stores
three decimal digits in each 10-bit group. decNumber and decimal hardware use DPD. IEEE
754 allows either encoding.
A BID encoding whose coefficient exceeds the format's maximum is non-canonical. IEEE 754
defines its value as zero. FromBits stores such an encoding unchanged, and arithmetic
treats it as zero. IsCanonical detects it, and Canonical converts it to the canonical
encoding. FromDpdBits always produces a canonical encoding.
Sqrt, Exp, Log, Log10, and Pow are implemented directly and tested against the
corpus. Exp2, Exp10, Cbrt, RootN, Hypot, Log2, ExpM1, LogP1, and the
related functions are computed from those.
Each type implements:
IFloatingPoint<T>, which includesINumber<T>,INumberBase<T>,ISignedNumber<T>, andIFloatingPointConstants<T>IMinMaxValue<T>IExponentialFunctions<T>,ILogarithmicFunctions<T>,IPowerFunctions<T>, andIRootFunctions<T>IUtf8SpanFormattableandIUtf8SpanParsable<T>
Generic numeric code works with all three types:
static T Mean<T>(ReadOnlySpan<T> values)
where T : INumber<T>
{
var total = T.Zero;
foreach (var value in values)
{
total += value;
}
return total / T.CreateChecked(values.Length);
}
var average = Mean<Decimal64>(samples);All required IEEE 754 operations are implemented and tested. The differences are:
- No alternate exception handling. IEEE 754 clause 8 describes trap handlers. Only
default exception handling is implemented: each operation returns the default result
and sets flags in the context's
Status. Arithmetic never throws. - No trigonometric or hyperbolic functions. IEEE 754-2019 lists these as recommended,
not required. decNumber does not implement them, and the corpus does not test them. As
a result, the types do not implement
IFloatingPointIeee754<T>. The other members of that interface are available as static methods with the same names:Epsilon,NaN, the infinities,NegativeZero,FusedMultiplyAdd,Ieee754Remainder,ILogB,ScaleB,BitIncrement, andBitDecrement. - Two definitions of max and min. IEEE 754-2019
maximumreturns NaN if either operand is NaN. The specification'smaxreturns the other operand when one is a quiet NaN.MaxandMinuse the IEEE 754-2019 definition.MaxNumber,MinNumber, and the overloads that take a context use the specification's definition. The same applies toMaxMagnitudeandMinMagnitude. ILogBuses .NET conventions for special values. It returnsint.MinValuefor zero andint.MaxValuefor NaN and infinity. The specification'slogbreturns -Infinity, NaN, and +Infinity.LogBimplements the specification's version and returns a decimal.ScaleBscales by powers of ten, as IEEE 754 defines it for decimal formats.double.ScaleBscales by powers of two. A scale value outside the valid range is an invalid operation and returns NaN.double.ScaleBreturns infinity in that case.Round(value, digits)does not add trailing zeros. If the value already hasdigitsor fewer decimal places, it is returned unchanged. UseQuantizeto set an exact number of places.- Equality and ordering follow .NET conventions for NaN, as described under Comparison.
- Four recommended operations are missing:
quantum(x),getPayload,setPayload, andsetPayloadSignaling.sameQuantumandquantizeare implemented. NaN payloads are preserved through arithmetic and conversion, and are parsed and formatted, for exampleNaN255.
Decimal32 stores its BID encoding in a uint and computes in 64-bit integers. With
7 digits, every intermediate result fits in 64 bits: a product has at most 14 digits, an
aligned sum at most 20, a scaled dividend 14, and a square-root radicand 16. Division
uses one double division followed by an integer correction. Square root uses
Math.Sqrt followed by an exact check. See design/Decimal32.md.
Decimal64 stores its BID encoding in a ulong and computes in 64-bit integers,
without UInt128 or BigInteger. Products are formed from 8-digit halves into two
base-10^16 limbs. Division by a power of ten uses multiplication by a precomputed
reciprocal. See design/Decimal64.md.
Decimal128 stores its BID encoding in two 64-bit words and computes with two- and
four-word integers. UInt128 is used only by ToBits and FromBits, and BigInteger
is not used. Division uses the Möller–Granlund 2-by-1 and 3-by-2 methods with a
reciprocal computed from a table, without a hardware divide instruction. See
design/Decimal128.md.
The elementary functions in all three types use a port of decNumber's arbitrary-precision engine. They need more digits than the format holds in order to round correctly. The engine's working storage is a fixed-size arena.
Nanoseconds per operation compared with decNumber's fixed-size C types. The operands are decbench's set: 1 to 16 digits, exponents from -40 to +40. Measured on one machine with BenchmarkDotNet's short job.
| operation | decDouble |
Decimal64 |
decQuad |
Decimal128 |
|---|---|---|---|---|
| add | 41.0 | 12.7 | 62.7 | 24.4 |
| multiply | 36.0 | 11.2 | 50.1 | 15.3 |
| divide | 121.1 | 31.0 | 192.2 | 68.7 |
| fma | 88.8 | 23.8 | 114.6 | 34.1 |
| compare | 12.8 | 7.4 | 25.3 | 12.9 |
| format into a span | 10.5 | 19.8 | 17.5 | 25.4 |
| from string | 27.5 | 18.1 | 31.9 | 33.0 |
decbench measures only formatting and parsing for decSingle. On the same operands,
decSingle formats in 7.7 ns and parses in 29.0 ns; Decimal32 takes 17.1 ns and
24.3 ns. On 1-to-7-digit operands, Decimal32 adds in 12.2 ns, multiplies in 7.3 ns, and
divides in 18.1 ns.
Summary:
- Add, multiply, divide, and fma are 2.5 to 4 times faster than the C.
- Compare is about 2 times faster.
- Parsing is about the same speed or faster.
- Formatting is 1.5 to 2.2 times slower. The C types store DPD and convert each 10-bit group to three digits with a table lookup. These types store a binary coefficient and must divide it to produce digits.
The C figures are the median of several runs. decbench times one pass per operation without warmup, so its results vary more between runs than the BenchmarkDotNet results. Treat ratios within about 10% of each other as equal.
To run the benchmarks:
dotnet run --project Benchmarks -c Release -- --filter '*'
dotnet test # unit tests, corpus, vector sample
./publish-dectest.sh # builds dectest into ~/bin
dectest TestData/DecTest TestData/Generated # the corpus
dectest --fetch-hfahmy TestData/Hfahmy/Full # downloads the full vector set
dectest --vectors TestData/Hfahmy/Full # runs it
dectest is the command-line runner in DecTest/, published as a native release build.
Run dectest with no arguments for its options. dotnet run --project DecTest -- runs the
same program without publishing it.
There are 692 tests. They run two sets of external test data.
The .decTest corpus, every applicable case: 10,562 for Decimal32, 19,850 for
Decimal64, and 20,237 for Decimal128. The corpus has two parts: the files distributed
with decNumber, and a generated set. The distributed files have no arithmetic cases for
decimal32 and no square-root cases for the fixed-size formats. The generated set covers
these. It was produced by running decNumber on the operands of the general test files. Each
case checks the result and the complete set of status flags.
Amr Sayed-Ahmed and Hossam A. H. Fahmy's test vectors, a committed sample of every
hundredth vector: 21,682 for Decimal64 and 89,495 for Decimal128. The vectors are
generated to cover the cases where decimal implementations often fail, such as
cancellation, sticky digits, and results just below a rounding boundary. Each vector checks the result,
including its exponent, and the IEEE 754 flags. The full set of 11.1 million vectors is too
large to commit; the commands above download and run it. There are no decimal32 vectors.
TestData/README.md describes each data set's source, license, and known defects.
Decimal32/ Decimal32 type
Decimal64/ Decimal64 type
Decimal128/ Decimal128 type
Decimals.Conformance/ .decTest and test-vector readers and runners
DecTest/ command-line front end for the runners
Tests/ unit tests, corpus tests, and vector tests
Benchmarks/ BenchmarkDotNet benchmarks
TestData/ .decTest corpus and test vectors
The arithmetic specification, the encodings, and the .decTest test cases are by Mike
Cowlishaw and are provided as-is; see https://speleotrove.com/decimal/. The test vectors
are by Amr Sayed-Ahmed and Hossam A. H. Fahmy of Cairo University; see
http://eece.cu.edu.eg/~hfahmy/arith_debug/. The files in TestData/ keep their original
headers and notices, and TestData/README.md gives each set's license and the works to
cite. This implementation shares no code with decNumber.