Decimal Structure

Syntax

'Declaration
<ComVisibleAttribute(True)> _
Public Structure Decimal _
    Implements IFormattable, IComparable, IConvertible, IComparable(Of Decimal),  _
    IEquatable(Of Decimal)

[ComVisibleAttribute(true)]
public struct Decimal : IFormattable, IComparable, 
    IConvertible, IComparable<decimal>, IEquatable<decimal>

Constructors

	Name	Description
	Decimal(Double)	Initializes a new instance of Decimal to the value of the specified double-precision floating-point number.
	Decimal(Int32)	Initializes a new instance of Decimal to the value of the specified 32-bit signed integer.
	Decimal(array<Int32[])	Initializes a new instance of Decimal to a decimal value represented in binary and contained in a specified array.
	Decimal(Int64)	Initializes a new instance of Decimal to the value of the specified 64-bit signed integer.
	Decimal(Single)	Initializes a new instance of Decimal to the value of the specified single-precision floating-point number.
	Decimal(UInt32)	Initializes a new instance of Decimal to the value of the specified 32-bit unsigned integer.
	Decimal(UInt64)	Initializes a new instance of Decimal to the value of the specified 64-bit unsigned integer.
	Decimal(Int32, Int32, Int32, Boolean, Byte)	Initializes a new instance of Decimal from parameters specifying the instance's constituent parts.

Top

Methods

	Name	Description
	Add	Adds two specified Decimal values.
	Ceiling	Returns the smallest integral value greater than or equal to the specified decimal number.
	Compare	Compares two specified Decimal values and returns an integer that indicates whether the first value is greater than, less than, or equal to the second value.
	CompareTo(Decimal)	Compares this instance to a specified Decimal object and returns an integer that indicates whether the value of this instance is greater than, less than, or equal to the value of the specified Decimal.
	CompareTo(Object)	Compares this instance to a specified Object and returns an integer that indicates whether the value of this instance is greater than, less than, or equal to the value of the specified Object.
	Divide	Divides two specified Decimal values.
	Equals(Decimal)	Returns a value indicating whether this instance and a specified Decimal object represent the same value.
	Equals(Object)	Returns a value indicating whether this instance and a specified Object represent the same type and value. (Overrides ValueType.Equals(Object).)
	Equals(Decimal, Decimal)	Returns a value indicating whether two specified instances of Decimal represent the same value.
	Finalize	Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
	Floor	Rounds a specified Decimal number to the closest integer toward negative infinity.
	GetBits	Converts the value of a specified instance of Decimal to its equivalent binary representation.
	GetHashCode	Returns the hash code for this instance. (Overrides ValueType.GetHashCode().)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	GetTypeCode	Returns the TypeCode for value type Decimal.
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	Multiply	Multiplies two specified Decimal values.
	Negate	Returns the result of multiplying the specified Decimal value by negative one.
	Parse(String)	Converts the string representation of a number to its Decimal equivalent.
	Parse(String, NumberStyles)	Converts the string representation of a number in a specified style to its Decimal equivalent.
	Parse(String, IFormatProvider)	Converts the string representation of a number to its Decimal equivalent using the specified culture-specific format information.
	Parse(String, NumberStyles, IFormatProvider)	Converts the string representation of a number to its Decimal equivalent using the specified style and culture-specific format.
	Remainder	Computes the remainder after dividing two Decimal values.
	Round	Rounds a Decimal value to a specified number of decimal places.
	Subtract	Subtracts one specified Decimal value from another.
	ToByte	Converts the value of the specified Decimal to the equivalent 8-bit unsigned integer.
	ToDouble	Converts the value of the specified Decimal to the equivalent double-precision floating-point number.
	ToInt16	Converts the value of the specified Decimal to the equivalent 16-bit signed integer.
	ToInt32	Converts the value of the specified Decimal to the equivalent 32-bit signed integer.
	ToInt64	Converts the value of the specified Decimal to the equivalent 64-bit signed integer.
	ToSByte	Converts the value of the specified Decimal to the equivalent 8-bit signed integer.
	ToSingle	Converts the value of the specified Decimal to the equivalent single-precision floating-point number.
	ToString()	Converts the numeric value of this instance to its equivalent string representation. (Overrides ValueType.ToString().)
	ToString(IFormatProvider)	Converts the numeric value of this instance to its equivalent string representation using the specified culture-specific format information.
	ToString(String)	Converts the numeric value of this instance to its equivalent string representation, using the specified format.
	ToString(String, IFormatProvider)	Converts the numeric value of this instance to its equivalent string representation using the specified format and culture-specific format information.
	ToUInt16	Converts the value of the specified Decimal to the equivalent 16-bit unsigned integer.
	ToUInt32	Converts the value of the specified Decimal to the equivalent 32-bit unsigned integer.
	ToUInt64	Converts the value of the specified Decimal to the equivalent 64-bit unsigned integer.
	Truncate	Returns the integral digits of the specified Decimal; any fractional digits are discarded.
	TryParse(String, Decimal%)	Converts the string representation of a number to its Decimal equivalent. A return value indicates whether the conversion succeeded or failed.
	TryParse(String, NumberStyles, IFormatProvider, Decimal%)	Converts the string representation of a number to its Decimal equivalent using the specified style and culture-specific format. A return value indicates whether the conversion succeeded or failed.

Top

Operators

	Name	Description
	Addition	Adds two specified Decimal values.
	Decrement	Decrements the Decimal operand by one.
	Division	Divides two specified Decimal values.
	Equality	Returns a value indicating whether two instances of Decimal are equal.
	Explicit(Decimal to UInt16)	Converts a Decimal to a 16-bit unsigned integer.
	Explicit(Decimal to SByte)	Converts a Decimal to an 8-bit signed integer.
	Explicit(Decimal to UInt32)	Converts a Decimal to a 32-bit unsigned integer.
	Explicit(Decimal to Char)	Converts a Decimal to a Unicode character.
	Explicit(Decimal to Byte)	Converts a Decimal to an 8-bit unsigned integer.
	Explicit(Decimal to Int64)	Converts a Decimal to a 64-bit signed integer.
	Explicit(Decimal to Double)	Converts a Decimal to a double-precision floating-point number.
	Explicit(Decimal to Int16)	Converts a Decimal to a 16-bit signed integer.
	Explicit(Decimal to UInt64)	Converts a Decimal to a 64-bit unsigned integer.
	Explicit(Decimal to Single)	Converts a Decimal to a single-precision floating-point number.
	Explicit(Decimal to Int32)	Converts a Decimal to a 32-bit signed integer.
	Explicit(Double to Decimal)	Converts a double-precision floating-point number to a Decimal.
	Explicit(Single to Decimal)	Converts a single-precision floating-point number to a Decimal.
	GreaterThan	Returns a value indicating whether a specified Decimal is greater than another specified Decimal.
	GreaterThanOrEqual	Returns a value indicating whether a specified Decimal is greater than or equal to another specified Decimal.
	Implicit(Byte to Decimal)	Converts an 8-bit unsigned integer to a Decimal.
	Implicit(Char to Decimal)	Converts a Unicode character to a Decimal.
	Implicit(Int16 to Decimal)	Converts a 16-bit signed integer to a Decimal.
	Implicit(Int32 to Decimal)	Converts a 32-bit signed integer to a Decimal.
	Implicit(Int64 to Decimal)	Converts a 64-bit signed integer to a Decimal.
	Implicit(SByte to Decimal)	Converts an 8-bit signed integer to a Decimal.
	Implicit(UInt16 to Decimal)	Converts a 16-bit unsigned integer to a Decimal.
	Implicit(UInt32 to Decimal)	Converts a 32-bit unsigned integer to a Decimal.
	Implicit(UInt64 to Decimal)	Converts a 64-bit unsigned integer to a Decimal.
	Increment	Increments the Decimal operand by 1.
	Inequality	Returns a value indicating whether two instances of Decimal are not equal.
	LessThan	Returns a value indicating whether a specified Decimal is less than another specified Decimal.
	LessThanOrEqual	Returns a value indicating whether a specified Decimal is less than or equal to another specified Decimal.
	Modulus	Returns the remainder resulting from dividing two specified Decimal values.
	Multiply	Multiplies two specified Decimal values.
	Subtraction	Subtracts two specified Decimal values.
	UnaryNegation	Negates the value of the specified Decimal operand.
	UnaryPlus	Returns the value of the Decimal operand (the sign of the operand is unchanged).

Top

Fields

	Name	Description
	MaxValue	Represents the largest possible value of Decimal. This field is constant and read-only.
	MinusOne	Represents the number negative one (-1).
	MinValue	Represents the smallest possible value of Decimal. This field is constant and read-only.
	One	Represents the number one (1).
	Zero	Represents the number zero (0).

Top

Explicit Interface Implementations

	Name	Description
	IConvertible.ToBoolean	Infrastructure. For a description of this member, see IConvertible.ToBoolean.
	IConvertible.ToByte	Infrastructure. For a description of this member, see IConvertible.ToByte.
	IConvertible.ToChar	Infrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
	IConvertible.ToDateTime	Infrastructure. This conversion is not supported. Attempting to use this method throws an InvalidCastException.
	IConvertible.ToDecimal	Infrastructure. For a description of this member, see IConvertible.ToDecimal.
	IConvertible.ToDouble	Infrastructure. For a description of this member, see IConvertible.ToDouble.
	IConvertible.ToInt16	Infrastructure. For a description of this member, see IConvertible.ToInt16.
	IConvertible.ToInt32	Infrastructure. For a description of this member, see IConvertible.ToInt32.
	IConvertible.ToInt64	Infrastructure. For a description of this member, see IConvertible.ToInt64.
	IConvertible.ToSByte	Infrastructure. For a description of this member, see IConvertible.ToSByte.
	IConvertible.ToSingle	Infrastructure. For a description of this member, see IConvertible.ToSingle.
	IConvertible.ToType	Infrastructure. For a description of this member, see IConvertible.ToType.
	IConvertible.ToUInt16	Infrastructure. For a description of this member, see IConvertible.ToUInt16.
	IConvertible.ToUInt32	Infrastructure. For a description of this member, see IConvertible.ToInt32.
	IConvertible.ToUInt64	Infrastructure. For a description of this member, see IConvertible.ToInt64.

Top

Remarks

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 Decimal value type is appropriate for financial calculations requiring 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 rather than 1.

Dim dividend As Decimal = Decimal.One
Dim divisor As Decimal = 3
' The following displays 0.9999999999999999999999999999
outputBlock.Text &= dividend / divisor * divisor & vbCrLf

decimal dividend = Decimal.One;
decimal divisor = 3;
// The following displays 0.9999999999999999999999999999
outputBlock.Text += dividend / divisor * divisor + "\n";

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.

Dim dividend As Decimal = Decimal.One
Dim divisor As Decimal = 3
' The following displays 1.00
outputBlock.Text += Math.Round(dividend / divisor * divisor, 2) & vbCrLf

decimal dividend = Decimal.One;
decimal divisor = 3;
// The following displays 1.00
outputBlock.Text += Math.Round(dividend / divisor * divisor, 2) + "\n";

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 consists of a 1-bit sign, a 96-bit integer number, and a scaling factor used to divide the 96-bit integer and specify what portion of it is a decimal fraction. The scaling factor is implicitly the number 10, raised to an exponent ranging from 0 to 28. Therefore, the binary representation of a Decimal value is of the form, ((-296 to 296) / 10(0 to 28)), where -296-1 is equal to MinValue, and 296-1 is equal to MaxValue.

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

Conversion Considerations

Implemented Interfaces

Examples

The following code example demonstrates the use of Decimal.

' 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

/// <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";
   }
}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Thread Safety

All members of this type are thread safe. Members that appear to modify instance state actually return a new instance initialized with the new value. As with any other type, reading and writing to a shared variable that contains an instance of this type must be protected by a lock to guarantee thread safety.

Caution:
Assigning an instance of this type is not thread safe on all hardware platforms because the binary representation of that instance might be too large to assign in a single atomic operation.

See Also

Reference