Table of Contents

Working with BigDecimal

BigDecimal is an immutable, value-equatable arbitrary-precision decimal number. Unlike System.Decimal - which is a fixed 128-bit type capped at 28-29 significant digits and an exponent range of 100 to 10-28 - BigDecimal grows to whatever precision a value requires. It stores an arbitrary-magnitude BigInteger unscaled value together with a non-negative int scale, so the represented number is:

value = unscaledValue × 10^-scale

Every value is held in one canonical form, with trailing fractional zeros removed: 12.340 is (unscaledValue: 1234, scale: 2), the same value as 12.34. There is no MinValue or MaxValue: the unscaled value is unbounded, like BigInteger. The scale is an int, so an operation whose scale would leave that range (a Multiply or Pow of values with extreme scales) throws OverflowException, and the (BigInteger, int) constructor rejects a scale below -1,000,000 with ArgumentOutOfRangeException.

BigDecimal implements the full INumber<BigDecimal> / ISignedNumber<BigDecimal> generic-math surface, so it composes with INumber<T>-constrained algorithms without a bespoke wrapper.

When to reach for BigDecimal

Need Type
Exact fractions such as 1/3, continued fractions, rational approximation Fraction<T>
Fixed-scale money within the decimal range (≤ 28 digits) System.Decimal
Decimal values that exceed decimal's precision or exponent range BigDecimal

BigDecimal holds one canonical form: trailing zeros are removed, so 1.0, 1.00, and 1 share one representation (scale 0) and compare and hash equal. It cannot record a value's written scale; to show a fixed number of places, format with F<n> (ToString("F2")), and use decimal if the written scale must survive.

Creating values

using System.Numerics;
using Bodu.Numerics;

// From an unscaled value and scale directly.
BigDecimal a = new BigDecimal(new BigInteger(12340), 3);  // 12.34 - canonical (1234, scale 2)

// Implicit lifts from the exact integer and decimal types.
BigDecimal fromInt     = 42;
BigDecimal fromLong    = 9_000_000_000L;
BigDecimal fromBigInt  = (BigInteger)1 << 200;   // exact, far beyond decimal
BigDecimal fromDecimal = 0.25m;                  // exact 0.25

// Parsing accepts plain and scientific decimal text.
BigDecimal parsed = BigDecimal.Parse("123456789012345678901234567890.123456789",
    CultureInfo.InvariantCulture);
BigDecimal sci    = BigDecimal.Parse("6.022e23", CultureInfo.InvariantCulture);

// Named constants.
BigDecimal zero = BigDecimal.Zero;
BigDecimal one  = BigDecimal.One;
BigDecimal ten  = BigDecimal.Ten;

double does not lift implicitly, because the nearest double to a written decimal is rarely that decimal. Convert deliberately:

BigDecimal fromDouble  = (BigDecimal)0.1;              // 0.1 - the shortest round-trip text of 0.1d, not its binary expansion
BigDecimal shortest    = BigDecimal.FromDouble(0.1);   // same value; explicit intent

Inspecting a value

BigDecimal v = BigDecimal.Parse("12.340", CultureInfo.InvariantCulture);   // 12.34 - the trailing zero is dropped

BigInteger unscaled = v.UnscaledValue;   // 1234
int scale           = v.Scale;           // 2
int precision       = v.Precision;       // 4  - total significant digits
int sign            = v.Sign;            // 1  (-1, 0, or 1)

bool isZero     = v.IsZero;
bool isInteger  = v.IsInteger;           // false - has a fractional part
bool isNegative = v.IsNegative;
bool isPositive = v.IsPositive;

// Deconstruct into (unscaledValue, scale).
var (mantissa, s) = v;

Arithmetic

Addition, subtraction, and multiplication are exact - the result carries whatever scale is needed to represent it with no loss:

BigDecimal sum  = BigDecimal.Add(0.1m, 0.2m);         // 0.3 exactly
BigDecimal diff = BigDecimal.Subtract(5m, 0.001m);    // 4.999
BigDecimal prod = BigDecimal.Multiply(1.5m, 1.5m);    // 2.25

BigDecimal neg  = BigDecimal.Negate(sum);
BigDecimal abs  = BigDecimal.Abs(neg);
BigDecimal pow  = BigDecimal.Pow(2m, 10);             // 1024

// Operators mirror the named methods.
BigDecimal total = (BigDecimal)0.1m + 0.2m - 0.05m;   // 0.25

Division and precision

Decimal division is not generally terminating (1/3), so BigDecimal cannot divide exactly and unboundedly at the same time. The contract:

  • The / operator and the two-argument Divide(BigDecimal, BigDecimal) compute the quotient to a default working precision of 50 fractional digits, rounded half-to-even, then strip trailing zeros. This is enough for the common case while staying deterministic.
  • For full control, use Divide(BigDecimal dividend, BigDecimal divisor, int scale, MidpointRounding mode) to fix the result scale and rounding mode explicitly.
BigDecimal third = BigDecimal.Divide(1m, 3m);                                   // 0.3333…(50 digits)
BigDecimal cents = BigDecimal.Divide(10m, 3m, scale: 2, MidpointRounding.ToEven); // 3.33
BigDecimal rem   = BigDecimal.Remainder(10m, 3m);                               // 1

Rounding and scale

BigDecimal v = BigDecimal.Parse("2.455", CultureInfo.InvariantCulture);

BigDecimal r2 = BigDecimal.Round(v, 2, MidpointRounding.ToEven);  // 2.46
BigDecimal r0 = BigDecimal.Round(v);                              // 2  (default scale 0)

BigDecimal floor    = BigDecimal.Floor(v);       // 2
BigDecimal ceiling  = BigDecimal.Ceiling(v);     // 3
BigDecimal truncate = BigDecimal.Truncate(v);    // 2  (toward zero)

Comparison and equality

Equality and ordering are by numeric value, and every value is canonical, so text written with different trailing zeros parses to equal values:

BigDecimal a = BigDecimal.Parse("1.0", CultureInfo.InvariantCulture);
BigDecimal b = BigDecimal.Parse("1.00", CultureInfo.InvariantCulture);

bool equal = a == b;                       // true
bool sameMin = BigDecimal.Min(a, b) == a;  // true - the values are equal, so Min returns either

// GetHashCode() is consistent with value equality: a and b hash equal.

Formatting and parsing

BigDecimal implements IFormattable, ISpanFormattable, IUtf8SpanFormattable, IParsable, ISpanParsable, and IUtf8SpanParsable. The G (general, plain culture-aware decimal) and F (fixed-point) standard specifiers are supported. As with the rest of the library, an IFormatProvider controls only the decimal separator and sign glyphs; the digit sequence is culture-invariant.

BigDecimal v = BigDecimal.Parse("1234.5", CultureInfo.InvariantCulture);

string general = v.ToString();                               // "1234.5"
string fixed2  = v.ToString("F2", CultureInfo.InvariantCulture); // "1234.50"

// The span and UTF-8 surfaces currently format through an intermediate string.
Span<char> buffer = stackalloc char[32];
v.TryFormat(buffer, out int written, "G", CultureInfo.InvariantCulture);

Generic math

Because BigDecimal satisfies INumber<BigDecimal>, it flows through generic-math algorithms and the CreateChecked / CreateTruncating conversion factories. Those factories are static virtual members of INumberBase<TSelf>, so - as with Fraction<T> - they are reached through a constrained type parameter rather than called as BigDecimal.CreateChecked(...) on the concrete type:

static T Sum<T>(params T[] values) where T : INumber<T>
{
    T acc = T.Zero;
    foreach (T value in values)
        acc += value;
    return acc;
}

static T FromInt32<T>(int value) where T : INumber<T> =>
    T.CreateChecked(value);

BigDecimal exact = Sum<BigDecimal>(0.1m, 0.2m, 0.3m);  // 0.6 exactly
BigDecimal five  = FromInt32<BigDecimal>(5);           // T.CreateChecked via the constraint
int back         = int.CreateTruncating(five);         // 5 - the BCL primitives expose the factories publicly

The classification predicates (IsInteger, IsEvenInteger, IsNegative, …) are exposed as static members of INumberBase<T> and are reached through a generic constraint, matching the BCL numeric types. Radix is 10.

Conversions

To How Notes
BigInteger (BigInteger)value / value.ToBigInteger() Truncates toward zero.
decimal (decimal)value / value.ToDecimal() Throws OverflowException when the value exceeds decimal's range; value.TryToDecimal(out var d) reports false instead of throwing.
double (double)value / value.ToDouble() Nearest double; may lose precision, and saturates to ±Infinity outside the finite range - value.TryToDouble(out var d) reports false in that case.
from double (BigDecimal)d / BigDecimal.FromDouble(d) Non-finite input throws.
from decimal implicit / BigDecimal.FromDecimal(d) Exact.

JSON serialization

Like the rest of Bodu.Numerics, the core type carries no [JsonConverter] attribute - JSON support ships in the companion Bodu.Numerics.Serialization.Json package. Register the converters with a single call and pick a wire shape:

using Bodu.Numerics.Serialization.Json;

var options = new JsonSerializerOptions()
    .AddNumericsJsonConverters(NumericsJsonPolicy.Strict);

// Strict - canonical object form (the trailing zero is dropped):
//   {"unscaledValue":1234,"scale":2}
// Compact - the plain decimal string:
//   "12.34"
string json = JsonSerializer.Serialize(
    BigDecimal.Parse("12.340", CultureInfo.InvariantCulture), options);

The Strict object shape writes the unscaled value as a raw JSON number, so an arbitrary-magnitude mantissa round-trips without precision loss. The Compact shape writes a string rather than a bare JSON number, because many JSON consumers silently narrow long numbers to IEEE-754 double.

See also