/**
* 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. 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 {@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,
MathContext context,
out BigDecimal remainder)
{
return(BigDecimalMath.DivideAndRemainder(a, b, context, out remainder));
}
/**
* Returns a new {@code BigDecimal} instance with the specified scale.
* <p>
* If the new scale is greater than the old scale, then additional zeros are
* added to the unscaled value. In this case no rounding is necessary.
* <p>
* If the new scale is smaller than the old scale, then trailing digits are
* removed. If these trailing digits are not zero, then the remaining
* unscaled value has to be rounded. For this rounding operation the
* specified rounding mode is used.
*
* @param newScale
* scale of the result returned.
* @param roundingMode
* rounding mode to be used to round the result.
* @return a new {@code BigDecimal} instance with the specified scale.
* @throws NullPointerException
* if {@code roundingMode == null}.
* @throws ArithmeticException
* if {@code roundingMode == ROUND_UNNECESSARY} and rounding is
* necessary according to the given scale.
*/
public static BigDecimal Scale(BigDecimal number, int newScale, RoundingMode roundingMode)
{
if (!Enum.IsDefined(typeof(RoundingMode), roundingMode))
{
throw new ArgumentException();
}
return(BigDecimalMath.Scale(number, newScale, roundingMode));
}
/// <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));
}
/**
* 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));
}
/**
* 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} 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 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 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));
}
/// <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));
}
/// <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));
}
