Struct BigDecimal
Represents an arbitrary precision decimal.
Implements
Namespace: Singulink.Numerics
Assembly: Singulink.Numerics.BigDecimal.dll
Syntax
public readonly struct BigDecimal : IFloatingPoint<BigDecimal>, IFloatingPointConstants<BigDecimal>, INumber<BigDecimal>, IComparable, IComparable<BigDecimal>, IComparisonOperators<BigDecimal, BigDecimal, bool>, IModulusOperators<BigDecimal, BigDecimal, BigDecimal>, ISignedNumber<BigDecimal>, INumberBase<BigDecimal>, IEquatable<BigDecimal>, ISpanFormattable, IFormattable, ISpanParsable<BigDecimal>, IParsable<BigDecimal>, IAdditionOperators<BigDecimal, BigDecimal, BigDecimal>, IAdditiveIdentity<BigDecimal, BigDecimal>, IDecrementOperators<BigDecimal>, IDivisionOperators<BigDecimal, BigDecimal, BigDecimal>, IEqualityOperators<BigDecimal, BigDecimal, bool>, IIncrementOperators<BigDecimal>, IMultiplicativeIdentity<BigDecimal, BigDecimal>, IMultiplyOperators<BigDecimal, BigDecimal, BigDecimal>, ISubtractionOperators<BigDecimal, BigDecimal, BigDecimal>, IUnaryNegationOperators<BigDecimal, BigDecimal>, IUnaryPlusOperators<BigDecimal, BigDecimal>, IUtf8SpanFormattable, IUtf8SpanParsable<BigDecimal>Remarks
This implementation of big decimal always stores values with the minimum precision possible to accurately represent the value in order to conserve memory and maintain optimal performance of operations on values.
All operations on BigDecimal values are exact except division in the case of a repeating decimal result. If the result of the division cannot be exactly represented in decimal form then the largest of the dividend precision, divisor precision and the specified maximum extended precision is used to represent the result. You can specify the maximum extended precision to use for each division operation by calling the Divide(BigDecimal, BigDecimal, int, RoundingMode) method. The DivideExact(BigDecimal, BigDecimal) and TryDivideExact(BigDecimal, BigDecimal, out BigDecimal) methods can be used for division operations that are expected to return exact results.
The standard division operator (/) first attempts to do an exact division and falls back to extended precision division using MaxExtendedDivisionPrecision as the maximum extended precision parameter. It is recommended that you always use the division methods and specify
the maximum extended precision instead of depending on the default of the operator.
Addition and subtraction are fully commutative and associative for all converted data types. Combined with its arbitrary precision, that makes BigDecimal a great data type to store aggregate totals that can freely add and subtract values in any order without accruing inaccuracies over time or overflowing.
Conversions from floating-point types (float/double) default to Truncate mode in order to match the behavior of floating point to decimal conversions, but there are several conversion modes available that are each suitable in different situations. You can use the FromSingle(float, FloatConversion) or FromDouble(double, FloatConversion) methods to specify a different conversion mode.
Constructors
| Name | Description |
|---|---|
| BigDecimal(BigInteger, int) | Initializes a new instance of the BigDecimal struct. |
Properties
| Name | Description |
|---|---|
| DecimalPlaces | Gets the number of digits that appear after the decimal point. |
| IsOne | Gets a value indicating whether the current value is 1. |
| IsPowerOfTen | Gets a value indicating whether the current value is a power of 10 (i.e. 0.1, 1, 10, 100, etc.). |
| IsZero | Gets a value indicating whether the current value is 0. |
| MaxExtendedDivisionPrecision | Gets the maximum extended precision used by the division operator if the result is not exact (i.e. has repeating decimals). If the dividend or divisor precision is greater then that value is used instead. The current value is 50 but is subject to change. |
| MinusOne | Gets a value representing negative one (-1). |
| One | Gets a value representing one (1). |
| Precision | Gets the precision of this value, i.e. the total number of digits it contains (excluding any leading/trailing zeros). Zero values have a precision of 1. |
| Sign | Gets a number indicating the sign (negative, positive, or zero) of the current value. |
| Zero | Gets a value representing zero (0). |
Methods
| Name | Description |
|---|---|
| Abs(BigDecimal) | Gets the absolute value of the given value. |
| Ceiling(BigDecimal) | Rounds up to the nearest integral value. |
| CompareTo(BigDecimal) | Compares this to another BigDecimal. |
| CreateChecked<TOther>(TOther) | Creates an instance of BigDecimal from a value. |
| CreateSaturating<TOther>(TOther) | Creates an instance of BigDecimal from a value. |
| CreateTruncating<TOther>(TOther) | Creates an instance of BigDecimal from a value. |
| Divide(BigDecimal, BigDecimal, int, RoundingMode) | Performs a division operation using the specified maximum extended precision. |
| DivideExact(BigDecimal, BigDecimal) | Performs a division operation that results in an exact decimal answer (i.e. no repeating decimals). |
| DivideRounded(BigDecimal, BigDecimal, int, RoundingMode) | Performs a division operation that results in a rounded decimal answer. |
| Equals(BigDecimal) | Indicates whether this value and the specified other value are equal. |
| Equals(object?) | Indicates whether this value and the specified object are equal. |
| Floor(BigDecimal) | Rounds down to the nearest integral value. |
| FromDouble(double, FloatConversion) | Gets a BigDecimal representation of a double value. |
| FromSingle(float, FloatConversion) | Gets a BigDecimal representation of a float value. |
| GetHashCode() | Returns the hash code for this value. |
| IsEvenInteger(BigDecimal) | Determines whether a value represents an even integral value. |
| IsInteger(BigDecimal) | Determines whether a value represents an integral value. |
| IsNegative(BigDecimal) | Determines if a value is negative. |
| IsOddInteger(BigDecimal) | Determines whether a value represents an odd integral value. |
| IsPositive(BigDecimal) | Determines if a value is positive. |
| MaxMagnitude(BigDecimal, BigDecimal) | Compares to values to compute which has a greater magnitude. |
| MinMagnitude(BigDecimal, BigDecimal) | Compares to values to compute which has a lesser magnitude. |
| Parse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?) | Converts the string representation of a number to its decimal equivalent. |
| Parse(ReadOnlySpan<char>, IFormatProvider?) | Converts the string representation of a number to its decimal equivalent. |
| Parse(string, NumberStyles, IFormatProvider?) | Converts the string representation of a number to its decimal equivalent. |
| Parse(string, IFormatProvider?) | Converts the string representation of a number to its decimal equivalent. |
| Pow(BigDecimal, int) | Returns the specified basis raised to the specified exponent. Exponent must be greater than or equal to 0. |
| Pow10(int) | Returns ten (10) raised to the specified exponent. |
| Round(BigDecimal, RoundingMode) | Rounds the value to the nearest integer using the given rounding mode. |
| Round(BigDecimal, int, RoundingMode) | Rounds the value to the specified number of decimal places using the given rounding mode. |
| RoundToPrecision(BigDecimal, int, RoundingMode) | Rounds the value to the specified precision using the given rounding mode. |
| ShiftDecimal(BigDecimal, int) | Shifts the decimal point of a value by the specified number of places, effectively multiplying or dividing the value by a power of 10. A positive shift moves the decimal point to the right (i.e. increases the exponent) and a negative shift moves the decimal point to the left (i.e. decreases the exponent). |
| ToString() | Returns a full-precision decimal form string representation of this value using the current culture. |
| ToString(string?, IFormatProvider?) | Returns a string representation of this value. |
| Truncate(BigDecimal) | Discards any fractional digits, effectively rounding towards zero. |
| TruncateToPrecision(BigDecimal, int) | Truncates the number to the given precision by removing any extra least significant digits. |
| TryDivideExact(BigDecimal, BigDecimal, out BigDecimal) | Performs a division operation that results in an exact decimal answer (i.e. no repeating decimals). |
| TryParse(ReadOnlySpan<char>, out BigDecimal) | Converts the string representation of a number to its decimal equivalent. |
| TryParse(ReadOnlySpan<char>, NumberStyles, IFormatProvider?, out BigDecimal) | Converts the string representation of a number to its decimal equivalent. |
| TryParse(ReadOnlySpan<char>, IFormatProvider?, out BigDecimal) | Converts the string representation of a number to its decimal equivalent. |
| TryParse(string?, out BigDecimal) | Converts the string representation of a number to its decimal equivalent. |
| TryParse(string?, NumberStyles, IFormatProvider?, out BigDecimal) | Converts the string representation of a number to its decimal equivalent. |
| TryParse(string?, IFormatProvider?, out BigDecimal) | Converts the string representation of a number to its decimal equivalent. |
Operators
| Name | Description |
|---|---|
| operator +(BigDecimal, BigDecimal) | Adds two values together to compute their sum. |
| operator --(BigDecimal) | Decrements a value. |
| operator /(BigDecimal, BigDecimal) | Divides one value by another to compute their quotient. |
| operator ==(BigDecimal, BigDecimal) | Compares two values to determine equality. |
| explicit operator byte(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a byte. |
| explicit operator decimal(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a decimal. |
| explicit operator double(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a double. |
| explicit operator short(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a short. |
| explicit operator int(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a int. |
| explicit operator long(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a long. |
| explicit operator BigInteger(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a BigInteger. |
| explicit operator sbyte(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a sbyte. |
| explicit operator float(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a float. |
| explicit operator ushort(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a ushort. |
| explicit operator uint(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a uint. |
| explicit operator ulong(BigDecimal) | Defines an explicit conversion from a BigDecimal value to a ulong. |
| explicit operator BigDecimal(double) | Defines an explicit conversion from a double value to a BigDecimal using the Truncate mode. |
| explicit operator BigDecimal(float) | Defines an explicit conversion from a float value to a BigDecimal using the Truncate mode. |
| operator >(BigDecimal, BigDecimal) | Compares two values to determine which is greater. |
| operator >=(BigDecimal, BigDecimal) | Compares two values to determine which is greater or equal. |
| implicit operator BigDecimal(byte) | Defines an implicit conversion from a byte value to a BigDecimal. |
| implicit operator BigDecimal(decimal) | Defines an implicit conversion from a decimal value to a BigDecimal. |
| implicit operator BigDecimal(short) | Defines an implicit conversion from a short value to a BigDecimal. |
| implicit operator BigDecimal(int) | Defines an implicit conversion from a int value to a BigDecimal. |
| implicit operator BigDecimal(long) | Defines an implicit conversion from a long value to a BigDecimal. |
| implicit operator BigDecimal(BigInteger) | Defines an implicit conversion from a BigInteger value to a BigDecimal. |
| implicit operator BigDecimal(sbyte) | Defines an implicit conversion from a sbyte value to a BigDecimal. |
| implicit operator BigDecimal(ushort) | Defines an implicit conversion from a ushort value to a BigDecimal. |
| implicit operator BigDecimal(uint) | Defines an implicit conversion from a uint value to a BigDecimal. |
| implicit operator BigDecimal(ulong) | Defines an implicit conversion from a ulong value to a BigDecimal. |
| operator ++(BigDecimal) | Increments a value. |
| operator !=(BigDecimal, BigDecimal) | Compares two values to determine inequality. |
| operator <(BigDecimal, BigDecimal) | Compares two values to determine which is less. |
| operator <=(BigDecimal, BigDecimal) | Compares two values to determine which is less or equal. |
| operator %(BigDecimal, BigDecimal) | Divides two values together to compute their modulus or remainder. |
| operator *(BigDecimal, BigDecimal) | Multiplies two values together to compute their product. |
| operator -(BigDecimal, BigDecimal) | Subtracts two values to compute their difference. |
| operator -(BigDecimal) | Computes the unary negation of a value. |
| operator +(BigDecimal) | Computes the unary plus of a value. |
Explicit Interface Implementations
| Name | Description |
|---|---|
| IComparable.CompareTo(object?) | Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object. |
| ISpanFormattable.TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider?) | Tries to format the value of the current instance into the provided span of characters. |
| IAdditiveIdentity<BigDecimal, BigDecimal>.AdditiveIdentity | Gets the additive identity of the current type. |
| IFloatingPointConstants<BigDecimal>.E | Gets the mathematical constant |
| IFloatingPointConstants<BigDecimal>.Pi | Gets the mathematical constant |
| IFloatingPointConstants<BigDecimal>.Tau | Gets the mathematical constant |
| IFloatingPoint<BigDecimal>.GetExponentByteCount() | Gets the number of bytes that will be written as part of TryWriteExponentLittleEndian(Span<byte>, out int). |
| IFloatingPoint<BigDecimal>.GetExponentShortestBitLength() | Gets the length, in bits, of the shortest two's complement representation of the current exponent. |
| IFloatingPoint<BigDecimal>.GetSignificandBitLength() | Gets the length, in bits, of the current significand. |
| IFloatingPoint<BigDecimal>.GetSignificandByteCount() | Gets the number of bytes that will be written as part of TryWriteSignificandLittleEndian(Span<byte>, out int). |
| IFloatingPoint<BigDecimal>.Round(BigDecimal, int, MidpointRounding) | Rounds a value to a specified number of fractional digits using the specified rounding mode. |
| IFloatingPoint<BigDecimal>.TryWriteExponentBigEndian(Span<byte>, out int) | Tries to write the current exponent, in big-endian format, to a given span. |
| IFloatingPoint<BigDecimal>.TryWriteExponentLittleEndian(Span<byte>, out int) | Tries to write the current exponent, in little-endian format, to a given span. |
| IFloatingPoint<BigDecimal>.TryWriteSignificandBigEndian(Span<byte>, out int) | Tries to write the current significand, in big-endian format, to a given span. |
| IFloatingPoint<BigDecimal>.TryWriteSignificandLittleEndian(Span<byte>, out int) | Tries to write the current significand, in little-endian format, to a given span. |
| IMultiplicativeIdentity<BigDecimal, BigDecimal>.MultiplicativeIdentity | Gets the multiplicative identity of the current type. |
| INumberBase<BigDecimal>.IsCanonical(BigDecimal) | Determines if a value is in its canonical representation. |
| INumberBase<BigDecimal>.IsComplexNumber(BigDecimal) | Determines if a value represents a complex number. |
| INumberBase<BigDecimal>.IsFinite(BigDecimal) | Determines if a value is finite. |
| INumberBase<BigDecimal>.IsImaginaryNumber(BigDecimal) | Determines if a value represents a pure imaginary number. |
| INumberBase<BigDecimal>.IsInfinity(BigDecimal) | Determines if a value is infinite. |
| INumberBase<BigDecimal>.IsNaN(BigDecimal) | Determines if a value is NaN. |
| INumberBase<BigDecimal>.IsNegativeInfinity(BigDecimal) | Determines if a value is negative infinity. |
| INumberBase<BigDecimal>.IsNormal(BigDecimal) | Determines if a value is normal. |
| INumberBase<BigDecimal>.IsPositiveInfinity(BigDecimal) | Determines if a value is positive infinity. |
| INumberBase<BigDecimal>.IsRealNumber(BigDecimal) | Determines if a value represents a real number. |
| INumberBase<BigDecimal>.IsSubnormal(BigDecimal) | Determines if a value is subnormal. |
| INumberBase<BigDecimal>.IsZero(BigDecimal) | Determines if a value is zero. |
| INumberBase<BigDecimal>.MaxMagnitudeNumber(BigDecimal, BigDecimal) | Compares two values to compute which has the greater magnitude and returning the other value if an input is |
| INumberBase<BigDecimal>.MinMagnitudeNumber(BigDecimal, BigDecimal) | Compares two values to compute which has the lesser magnitude and returning the other value if an input is |
| INumberBase<BigDecimal>.Radix | Gets the radix, or base, for the type. |
| INumberBase<BigDecimal>.TryConvertFromChecked<TOther>(TOther, out BigDecimal) | Tries to convert a value to an instance of the the current type, throwing an overflow exception for any values that fall outside the representable range of the current type. |
| INumberBase<BigDecimal>.TryConvertFromSaturating<TOther>(TOther, out BigDecimal) | Tries to convert a value to an instance of the the current type, saturating any values that fall outside the representable range of the current type. |
| INumberBase<BigDecimal>.TryConvertFromTruncating<TOther>(TOther, out BigDecimal) | Tries to convert a value to an instance of the the current type, truncating any values that fall outside the representable range of the current type. |
| INumberBase<BigDecimal>.TryConvertToChecked<TOther>(BigDecimal, out TOther) | Tries to convert an instance of the the current type to another type, throwing an overflow exception for any values that fall outside the representable range of the current type. |
| INumberBase<BigDecimal>.TryConvertToSaturating<TOther>(BigDecimal, out TOther) | Tries to convert an instance of the the current type to another type, saturating any values that fall outside the representable range of the current type. |
| INumberBase<BigDecimal>.TryConvertToTruncating<TOther>(BigDecimal, out TOther) | Tries to convert an instance of the the current type to another type, truncating any values that fall outside the representable range of the current type. |
| ISignedNumber<BigDecimal>.NegativeOne | Gets the value |