/// <remarks>
/// Returns a new <see cref="BigDecimal"/> whose value is <c>+this</c>.
/// </remarks>
/// <param name="mc">Rounding mode and precision for the result of this operation.</param>
/// <remarks>
/// The result is rounded according to the passed context <paramref name="mc"/>.
/// </remarks>
/// <returns>
/// Returns this decimal value rounded.
/// </returns>
public static BigDecimal Plus(BigDecimal number, MathContext mc)
{
return(Round(number, mc));
}
/**
* Returns a new {@code BigDecimal} whose value is the absolute value of
* {@code this}. The result is rounded according to the passed context
* {@code mc}.
*
* @param mc
* rounding mode and precision for the result of this operation.
* @return {@code abs(this)}
*/
public static BigDecimal Abs(BigDecimal value, MathContext mc)
{
return(Abs(Round(value, mc)));
}
/**
* Returns a new {@code BigDecimal} whose value is {@code +this}. The scale
* of the result is the same as the scale of this.
*
* @return {@code this}
*/
public static BigDecimal Plus(BigDecimal number)
{
return(number);
}
/// <summary>
/// Subtracts the given value from this instance of <see cref="BigDecimal"/>.
/// </summary>
/// <remarks>
/// </remarks>
/// <param name="subtrahend">The value to be subtracted from this <see cref="BigDecimal"/>.</param>
/// <returns>
/// Returns an instance of <see cref="BigDecimal"/> that is the result of the
/// subtraction of the given <paramref name="subtrahend"/> from this instance.
/// </returns>
/// <exception cref="ArgumentNullException">
/// If the given <paramref name="subtrahend"/> is <c>null</c>.
/// </exception>
public static BigDecimal Subtract(BigDecimal value, BigDecimal subtrahend)
{
return(BigDecimalMath.Subtract(value, subtrahend));
}
/**
* Returns a new {@code BigDecimal} whose value is the absolute value of
* {@code this}. The scale of the result is the same as the scale of this.
*
* @return {@code abs(this)}
*/
public static BigDecimal Abs(BigDecimal number)
{
return((number.Sign < 0) ? -number : number);
}
/**
* Returns a new {@code BigDecimal} instance with the specified scale. If
* the new scale is greater than the old scale, then additional zeros are
* added to the unscaled value. If the new scale is smaller than the old
* scale, then trailing zeros are removed. If the trailing digits are not
* zeros then an ArithmeticException is thrown.
* <p>
* If no exception is thrown, then the following equation holds: {@code
* x.setScale(s).compareTo(x) == 0}.
*
* @param newScale
* scale of the result returned.
* @return a new {@code BigDecimal} instance with the specified scale.
* @throws ArithmeticException
* if rounding would be necessary.
*/
public static BigDecimal Scale(BigDecimal number, int newScale)
{
return(Scale(number, newScale, RoundingMode.Unnecessary));
}
/**
* Returns the unit in the last place (ULP) of this {@code BigDecimal}
* instance. An ULP is the distance to the nearest big decimal with the same
* precision.
* <p>
* The amount of a rounding error in the evaluation of a floating-point
* operation is often expressed in ULPs. An error of 1 ULP is often seen as
* a tolerable error.
* <p>
* For class {@code BigDecimal}, the ULP of a number is simply 10^(-scale).
* <p>
* For example, {@code new BigDecimal(0.1).ulp()} returns {@code 1E-55}.
*
* @return unit in the last place (ULP) of this {@code BigDecimal} instance.
*/
public static BigDecimal Ulp(BigDecimal value)
{
return(BigDecimal.Create(1, value.Scale));
}
/**
* Returns a new {@code BigDecimal} whose value is the integral part of
* {@code this / divisor}. The quotient is rounded down towards zero to the
* next integer. The rounding mode passed with the parameter {@code mc} is
* not considered. But if the precision of {@code mc > 0} and the integral
* part requires more digits, then an {@code ArithmeticException} is thrown.
*
* @param divisor
* value by which {@code this} is divided.
* @param mc
* math context which determines the maximal precision of the
* result.
* @return integral part of {@code this / divisor}.
* @throws NullPointerException
* if {@code divisor == null} or {@code mc == null}.
* @throws ArithmeticException
* if {@code divisor == 0}.
* @throws ArithmeticException
* if {@code mc.getPrecision() > 0} and the result requires more
* digits to be represented.
*/
public static BigDecimal DivideToIntegral(BigDecimal a, BigDecimal b, MathContext context)
{
return(BigDecimalMath.DivideToIntegralValue(a, b, context));
}
/**
* Returns a {@code BigDecimal} array which contains the integral part of
* {@code this / divisor} at index 0 and the remainder {@code this %
* divisor} at index 1. The quotient is rounded down towards zero to the
* next integer.
*
* @param divisor
* value by which {@code this} is divided.
* @return {@code [this.divideToIntegralValue(divisor),
* this.remainder(divisor)]}.
* @throws NullPointerException
* if {@code divisor == null}.
* @throws ArithmeticException
* if {@code divisor == 0}.
* @see #divideToIntegralValue
* @see #remainder
*/
public static BigDecimal DivideAndRemainder(BigDecimal a, BigDecimal b, out BigDecimal remainder)
{
return(BigDecimalMath.DivideAndRemainder(a, b, out remainder));
}
/**
* Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
* The result is rounded according to the passed context {@code mc}. If the
* passed math context specifies precision {@code 0}, then this call is
* equivalent to {@code this.divide(divisor)}.
*
* @param divisor
* value by which {@code this} is divided.
* @param mc
* rounding mode and precision for the result of this operation.
* @return {@code this / divisor}.
* @throws NullPointerException
* if {@code divisor == null} or {@code mc == null}.
* @throws ArithmeticException
* if {@code divisor == 0}.
* @throws ArithmeticException
* if {@code mc.getRoundingMode() == UNNECESSARY} and rounding
* is necessary according {@code mc.getPrecision()}.
*/
public static BigDecimal Divide(BigDecimal a, BigDecimal b, MathContext context)
{
return(BigDecimalMath.Divide(a, b, context));
}
/**
* Returns a new {@code BigDecimal} whose value is the integral part of
* {@code this / divisor}. The quotient is rounded down towards zero to the
* next integer. For example, {@code 0.5/0.2 = 2}.
*
* @param divisor
* value by which {@code this} is divided.
* @return integral part of {@code this / divisor}.
* @throws NullPointerException
* if {@code divisor == null}.
* @throws ArithmeticException
* if {@code divisor == 0}.
*/
public static BigDecimal DivideToIntegral(BigDecimal a, BigDecimal b)
{
return(BigDecimalMath.DivideToIntegralValue(a, b));
}
/**
* Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
* As scale of the result the parameter {@code scale} is used. If rounding
* is required to meet the specified scale, then the specified rounding mode
* {@code roundingMode} is applied.
*
* @param divisor
* value by which {@code this} is divided.
* @param scale
* the scale of the result returned.
* @param roundingMode
* rounding mode to be used to round the result.
* @return {@code this / divisor} rounded according to the given rounding
* mode.
* @throws NullPointerException
* if {@code divisor == null} or {@code roundingMode == null}.
* @throws ArithmeticException
* if {@code divisor == 0}.
* @throws ArithmeticException
* if {@code roundingMode == RoundingMode.UNNECESSAR}Y and
* rounding is necessary according to the given scale and given
* precision.
*/
public static BigDecimal Divide(BigDecimal a, BigDecimal b, int scale, RoundingMode roundingMode)
{
return(BigDecimalMath.Divide(a, b, scale, roundingMode));
}
/**
* Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
* The scale of the result is the difference of the scales of {@code this}
* and {@code divisor}. If the exact result requires more digits, then the
* scale is adjusted accordingly. For example, {@code 1/128 = 0.0078125}
* which has a scale of {@code 7} and precision {@code 5}.
*
* @param divisor
* value by which {@code this} is divided.
* @return {@code this / divisor}.
* @throws NullPointerException
* if {@code divisor == null}.
* @throws ArithmeticException
* if {@code divisor == 0}.
* @throws ArithmeticException
* if the result cannot be represented exactly.
*/
public static BigDecimal Divide(BigDecimal a, BigDecimal b)
{
return(BigDecimalMath.Divide(a, b));
}
/// <summary>
/// Subtracts the given value from this instance of <see cref="BigDecimal"/>.
/// </summary>
/// <remarks>
/// <para>
/// This overload rounds the result of the operation to the <paramref name="mc">context</paramref>
/// provided as argument.
/// </para>
/// </remarks>
/// <param name="subtrahend">The value to be subtracted from this <see cref="BigDecimal"/>.</param>
/// <param name="mc">The context used to round the result of this operation.</param>
/// <returns>
/// Returns an instance of <see cref="BigDecimal"/> that is the result of the
/// subtraction of the given <paramref name="subtrahend"/> from this instance.
/// </returns>
/// <exception cref="ArgumentNullException">
/// If either of the given <paramref name="subtrahend"/> or <paramref name="mc"/> are <c>null</c>.
/// </exception>
public static BigDecimal Subtract(BigDecimal value, BigDecimal subtrahend, MathContext mc)
{
return(BigDecimalMath.Subtract(value, subtrahend, mc));
}
/**
* Returns a new {@code BigDecimal} whose value is the {@code -this}. The
* result is rounded according to the passed context {@code mc}.
*
* @param mc
* rounding mode and precision for the result of this operation.
* @return {@code -this}
*/
public static BigDecimal Negate(BigDecimal number, MathContext mc)
{
return(Negate(Round(number, mc)));
}
/**
* Returns a new {@code BigDecimal} whose value is {@code this *
* multiplicand}. The scale of the result is the sum of the scales of the
* two arguments.
*
* @param multiplicand
* value to be multiplied with {@code this}.
* @return {@code this * multiplicand}.
* @throws NullPointerException
* if {@code multiplicand == null}.
*/
public static BigDecimal Multiply(BigDecimal value, BigDecimal multiplicand)
{
return(BigDecimalMath.Multiply(value, multiplicand));
}
/**
* Returns the maximum of this {@code BigDecimal} and {@code val}.
*
* @param val
* value to be used to compute the maximum with this.
* @return {@code max(this, val}.
* @throws NullPointerException
* if {@code val == null}.
*/
public static BigDecimal Max(BigDecimal a, BigDecimal val)
{
return((a.CompareTo(val) >= 0) ? a : val);
}
/**
* Returns a new {@code BigDecimal} whose value is {@code this ^ n}. The
* scale of the result is {@code n} times the scales of {@code this}.
* <p>
* {@code x.pow(0)} returns {@code 1}, even if {@code x == 0}.
* <p>
* Implementation Note: The implementation is based on the ANSI standard
* X3.274-1996 algorithm.
*
* @param n
* exponent to which {@code this} is raised.
* @return {@code this ^ n}.
* @throws ArithmeticException
* if {@code n < 0} or {@code n > 999999999}.
*/
public static BigDecimal Pow(BigDecimal number, int exp)
{
return(BigDecimalMath.Pow(number, exp));
}
/**
* Returns a new {@code BigDecimal} instance where the decimal point has
* been moved {@code n} places to the right. If {@code n < 0} then the
* decimal point is moved {@code -n} places to the left.
* <p>
* The result is obtained by changing its scale. If the scale of the result
* becomes negative, then its precision is increased such that the scale is
* zero.
* <p>
* Note, that {@code movePointRight(0)} returns a result which is
* mathematically equivalent, but which has scale >= 0.
*
* @param n
* number of placed the decimal point has to be moved.
* @return {@code this * 10^n}.
*/
public static BigDecimal MovePointRight(BigDecimal number, int n)
{
return(BigDecimalMath.MovePoint(number, number.Scale - (long)n));
}
/**
* Returns a new {@code BigDecimal} whose value is {@code this ^ n}. The
* result is rounded according to the passed context {@code mc}.
* <p>
* Implementation Note: The implementation is based on the ANSI standard
* X3.274-1996 algorithm.
*
* @param n
* exponent to which {@code this} is raised.
* @param mc
* rounding mode and precision for the result of this operation.
* @return {@code this ^ n}.
* @throws ArithmeticException
* if {@code n < 0} or {@code n > 999999999}.
*/
public static BigDecimal Pow(BigDecimal number, int exp, MathContext context)
{
return(BigDecimalMath.Pow(number, exp, context));
}
/// <summary>
/// Adds a value to the current instance of <see cref="BigDecimal"/>,
/// rounding the result according to the provided context.
/// </summary>
/// <param name="augend">The value to be added to this instance.</param>
/// <param name="mc">The rounding mode and precision for the result of
/// this operation.</param>
/// <returns>
/// Returns a new <see cref="BigDecimal"/> whose value is <c>this + <paramref name="augend"/></c>.
/// </returns>
/// <exception cref="ArgumentNullException">
/// If the given <paramref name="augend"/> or <paramref name="mc"/> is <c>null</c>.
/// </exception>
public static BigDecimal Add(BigDecimal value, BigDecimal augend, MathContext mc)
{
return(BigDecimalMath.Add(value, augend, mc));
}
/// <summary>
/// Adds a value to the current instance of <see cref="BigDecimal"/>.
/// The scale of the result is the maximum of the scales of the two arguments.
/// </summary>
/// <param name="augend">The value to be added to this instance.</param>
/// <returns>
/// Returns a new {@code BigDecimal} whose value is <c>this + <paramref name="augend"/></c>.
/// </returns>
/// <exception cref="ArgumentNullException">
/// If the given <paramref name="augend"/> is <c>null</c>.
/// </exception>
public static BigDecimal Add(BigDecimal value, BigDecimal augend)
{
return(BigDecimalMath.Add(value, augend));
}
