System.Decimal struct

This article provides supplementary remarks to the reference documentation for this API.

The Decimal value type represents decimal numbers ranging from positive 79,228,162,514,264,337,593,543,950,335 to negative 79,228,162,514,264,337,593,543,950,335. The default value of a Decimal is 0. The Decimal value type is appropriate for financial calculations that require large numbers of significant integral and fractional digits and no round-off errors. The Decimal type does not eliminate the need for rounding. Rather, it minimizes errors due to rounding. For example, the following code produces a result of 0.9999999999999999999999999999 instead of 1.

decimal dividend = Decimal.One;
decimal divisor = 3;
// The following displays 0.9999999999999999999999999999 to the console
Console.WriteLine(dividend/divisor * divisor);

let dividend = Decimal.One
let divisor = 3m
// The following displays 0.9999999999999999999999999999 to the console
printfn $"{dividend/divisor * divisor}"

Dim dividend As Decimal = Decimal.One
Dim divisor As Decimal = 3
' The following displays 0.9999999999999999999999999999 to the console
Console.WriteLine(dividend/divisor * divisor)

When the result of the division and multiplication is passed to the Round method, the result suffers no loss of precision, as the following code shows.

decimal dividend = Decimal.One;
decimal divisor = 3;
// The following displays 1.00 to the console
Console.WriteLine(Math.Round(dividend/divisor * divisor, 2));

let dividend = Decimal.One
let divisor = 3m
// The following displays 1.00 to the console
printfn $"{Math.Round(dividend/divisor * divisor, 2)}"

Dim dividend As Decimal = Decimal.One
Dim divisor As Decimal = 3
' The following displays 1.00 to the console
Console.WriteLine(Math.Round(dividend/divisor * divisor, 2))

A decimal number is a floating-point value that consists of a sign, a numeric value where each digit in the value ranges from 0 to 9, and a scaling factor that indicates the position of a floating decimal point that separates the integral and fractional parts of the numeric value.

The binary representation of a Decimal value is 128-bits consisting of a 96-bit integer number, and a 32-bit set of flags representing things such as the sign and scaling factor used to specify what portion of it is a decimal fraction. Therefore, the binary representation of a Decimal value the form, ((-2⁹⁶ to 2⁹⁶) / 10^{(0 to 28)}), where -(2⁹⁶-1) is equal to MinValue, and 2⁹⁶-1 is equal to MaxValue. For more information about the binary representation of Decimal values and an example, see the Decimal(Int32[]) constructor and the GetBits method.

The scaling factor also preserves any trailing zeros in a Decimal number. Trailing zeros do not affect the value of a Decimal number in arithmetic or comparison operations. However, trailing zeros might be revealed by the ToString method if an appropriate format string is applied.

Conversion considerations

This type provides methods that convert Decimal values to and from SByte, Int16, Int32, Int64, Byte, UInt16, UInt32, and UInt64 values. Conversions from these integral types to Decimal are widening conversions that never lose information or throw exceptions.

Conversions from Decimal to any of the integral types are narrowing conversions that round the Decimal value to the nearest integer value toward zero. Some languages, such as C#, also support the conversion of Decimal values to Char values. If the result of these conversions cannot be represented in the destination type, an OverflowException exception is thrown.

The Decimal type also provides methods that convert Decimal values to and from Single and Double values. Conversions from Decimal to Single or Double are narrowing conversions that might lose precision but not information about the magnitude of the converted value. The conversion does not throw an exception.

Conversions from Single or Double to Decimal throw an OverflowException exception if the result of the conversion cannot be represented as a Decimal.

Perform operations on Decimal values

The Decimal type supports standard mathematical operations such as addition, subtraction, division, multiplication, and unary negation. You can also work directly with the binary representation of a Decimal value by calling the GetBits method.

To compare two Decimal values, you can use the standard numeric comparison operators, or you can call the CompareTo or Equals method.

You can also call the members of the Math class to perform a wide range of numeric operations, including getting the absolute value of a number, determining the maximum or minimum value of two Decimal values, getting the sign of a number, and rounding a number.

Examples

The following code example demonstrates the use of Decimal.

/// <summary>
/// Keeping my fortune in Decimals to avoid the round-off errors.
/// </summary>
class PiggyBank {
    protected decimal MyFortune;

    public void AddPenny() {
        MyFortune = Decimal.Add(MyFortune, .01m);
    }

    public decimal Capacity {
        get {
            return Decimal.MaxValue;
        }
    }

    public decimal Dollars {
        get {
            return Decimal.Floor(MyFortune);
        }
    }

    public decimal Cents {
        get {
            return Decimal.Subtract(MyFortune, Decimal.Floor(MyFortune));
        }
    }

    public override string ToString() {
        return MyFortune.ToString("C")+" in piggy bank";
    }
}

/// Keeping my fortune in Decimals to avoid the round-off errors.
type PiggyBank() =
    let mutable myFortune = 0m

    member _.AddPenny() =
        myFortune <- Decimal.Add(myFortune, 0.01m)

    member _.Capacity =
        Decimal.MaxValue

    member _.Dollars =
        Decimal.Floor myFortune

    member _.Cents =
        Decimal.Subtract(myFortune, Decimal.Floor myFortune)

    override _.ToString() =
        $"{myFortune:C} in piggy bank"

' Keeping my fortune in Decimals to avoid the round-off errors.
Class PiggyBank
    Protected MyFortune As Decimal

    Public Sub AddPenny()
        MyFortune = [Decimal].Add(MyFortune, 0.01D)
    End Sub

    Public ReadOnly Property Capacity() As Decimal
        Get
            Return [Decimal].MaxValue
        End Get
    End Property

    Public ReadOnly Property Dollars() As Decimal
        Get
            Return [Decimal].Floor(MyFortune)
        End Get
    End Property

    Public ReadOnly Property Cents() As Decimal
        Get
            Return [Decimal].Subtract(MyFortune, [Decimal].Floor(MyFortune))
        End Get
    End Property

    Public Overrides Function ToString() As String
        Return MyFortune.ToString("C") + " in piggy bank"
    End Function
End Class