org.decimal4j.api.MutableDecimal Maven / Gradle / Ivy
Show all versions of decimal4j Show documentation
/**
* The MIT License (MIT)
*
* Copyright (c) 2015-2016 decimal4j (tools4j), Marco Terzer
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package org.decimal4j.api;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.math.RoundingMode;
import org.decimal4j.scale.ScaleMetrics;
import org.decimal4j.truncate.OverflowMode;
import org.decimal4j.truncate.TruncationPolicy;
/**
* Interface implemented by mutable {@link Decimal} classes of different scales.
* Mutable Decimals modify their state when performing arithmetic operations;
* they represent the result after the operation. Arithmetic operations
* therefore return {@code this} as return value. Note however that the
* {@link #getScale() scale} of a Mutable Decimal does not change and remains
* constant throughout the lifetime of a {@code MutableDecimal} instance.
*
* Mutable Decimals may be preferred over {@link ImmutableDecimal} descendants
* e.g. if the allocation of new objects is undesired or if a chain of
* operations is performed.
*
* Mutable Decimals are NOT thread safe.
*
* @param
* the scale metrics type associated with this Decimal
*/
public interface MutableDecimal extends Decimal {
/**
* Sets {@code this} Decimal to 0 and returns {@code this} now representing
* zero.
*
* @return {@code this} Decimal after assigning the value {@code 0}
*/
MutableDecimal setZero();
/**
* Sets {@code this} Decimal to 1 and returns {@code this} now representing
* one.
*
* @return {@code this} Decimal after assigning the value {@code 1}
*/
MutableDecimal setOne();
/**
* Sets {@code this} Decimal to -1 and returns {@code this} now representing
* minus one.
*
* @return {@code this} Decimal after assigning the value {@code -1}
*/
MutableDecimal setMinusOne();
/**
* Sets {@code this} Decimal to the smallest positive value representable by
* this Mutable Decimal and returns {@code this} now representing one ULP.
*
* @return {@code this} Decimal after assigning the value
* ULP=10-scale
*/
MutableDecimal setUlp();
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}.
*
* @param value
* value to be set
* @return {@code this} Decimal after assigning the given {@code value}
*/
MutableDecimal set(Decimal value);
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}. The specified
* {@link Decimal} argument is rounded to the {@link #getScale() scale} of
* this mutable Decimal using {@link RoundingMode#HALF_UP} rounding. An
* exception is thrown if the specified value is too large to be represented
* as a Decimal of this mutable Decimal's scale.
*
* @param value
* value to be set
* @param roundingMode
* the rounding mode to apply during the conversion if necessary
* @return {@code this} Decimal after assigning:
* roundHALF_UP(value)
* @throws IllegalArgumentException
* if {@code value} is too large to be represented as a Decimal
* with the scale of this mutable Decimal
* @throws ArithmeticException
* if {@code roundingMode} is {@link RoundingMode#UNNECESSARY
* UNNESSESSARY} and rounding is necessary
*/
MutableDecimal set(Decimal value, RoundingMode roundingMode);
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}. An exception is thrown if
* the specified value is too large to be represented as a Decimal of this
* mutable Decimal's scale.
*
* @param value
* value to be set
* @return {@code this} Decimal after assigning the given {@code value}
* @throws IllegalArgumentException
* if {@code value} is too large to be represented as a Decimal
* with the scale of this mutable Decimal
*/
MutableDecimal set(long value);
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}. An exception is thrown if
* the specified value is too large to be represented as a Decimal of this
* mutable Decimal's scale.
*
* @param value
* value to be set
* @return {@code this} Decimal after assigning the given {@code value}
* @throws IllegalArgumentException
* if {@code value} is too large to be represented as a Decimal
* with the scale of this mutable Decimal
*/
MutableDecimal set(BigInteger value);
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}. The specified {@code float}
* argument is rounded to the {@link #getScale() scale} of this mutable
* Decimal using {@link RoundingMode#HALF_UP} rounding. An exception is
* thrown if the specified value is too large to be represented as a Decimal
* of this mutable Decimal's scale.
*
* @param value
* value to be set
* @return {@code this} Decimal after assigning:
* roundHALF_UP(value)
* @throws IllegalArgumentException
* if {@code value} is NaN or infinite or if the magnitude is
* too large for the float to be represented as a Decimal with
* the scale of this mutable Decimal
*/
MutableDecimal set(float value);
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}. The specified {@code float}
* argument is rounded to the {@link #getScale() scale} of this mutable
* Decimal using the specified {@code roundingMode}. An exception is thrown
* if the specified value is too large to be represented as a Decimal of
* this mutable Decimal's scale.
*
* @param value
* value to be set
* @param roundingMode
* the rounding mode to apply during the conversion if necessary
* @return {@code this} Decimal after assigning: round(value)
* @throws IllegalArgumentException
* if {@code value} is NaN or infinite or if the magnitude is
* too large for the float to be represented as a Decimal with
* the scale of this mutable Decimal
* @throws ArithmeticException
* if {@code roundingMode} is {@link RoundingMode#UNNECESSARY
* UNNESSESSARY} and rounding is necessary
*/
MutableDecimal set(float value, RoundingMode roundingMode);
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}. The specified {@code double}
* argument is rounded to the {@link #getScale() scale} of this mutable
* Decimal using {@link RoundingMode#HALF_UP} rounding. An exception is
* thrown if the specified value is too large to be represented as a Decimal
* of this mutable Decimal's scale.
*
* @param value
* value to be set
* @return {@code this} Decimal after assigning:
* roundHALF_UP(value)
* @throws IllegalArgumentException
* if {@code value} is NaN or infinite or if the magnitude is
* too large for the double to be represented as a Decimal with
* the scale of this mutable Decimal
*/
MutableDecimal set(double value);
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}. The specified {@code double}
* argument is rounded to the {@link #getScale() scale} of this mutable
* Decimal using the specified {@code roundingMode}. An exception is thrown
* if the specified value is too large to be represented as a Decimal of
* this mutable Decimal's scale.
*
* @param value
* value to be set
* @param roundingMode
* the rounding mode to apply during the conversion if necessary
* @return {@code this} Decimal after assigning: round(value)
* @throws IllegalArgumentException
* if {@code value} is NaN or infinite or if the magnitude is
* too large for the double to be represented as a Decimal with
* the scale of this mutable Decimal
* @throws ArithmeticException
* if {@code roundingMode} is {@link RoundingMode#UNNECESSARY
* UNNESSESSARY} and rounding is necessary
*/
MutableDecimal set(double value, RoundingMode roundingMode);
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}. The specified
* {@link BigDecimal} argument is rounded to the {@link #getScale() scale}
* of this mutable Decimal using {@link RoundingMode#HALF_UP} rounding. An
* exception is thrown if the specified value is too large to be represented
* as a Decimal of this mutable Decimal's scale.
*
* @param value
* value to be set
* @return {@code this} Decimal after assigning:
* roundHALF_UP(value)
* @throws IllegalArgumentException
* if {@code value} is too large to be represented as a Decimal
* with the scale of this mutable Decimal
*/
MutableDecimal set(BigDecimal value);
/**
* Sets {@code this} Decimal to the specified {@code value} and returns
* {@code this} now representing {@code value}. The specified
* {@link BigDecimal} argument is rounded to the {@link #getScale() scale}
* of this mutable Decimal using the specified {@code roundingMode}. An
* exception is thrown if the specified value is too large to be represented
* as a Decimal of this mutable Decimal's scale.
*
* @param value
* value to be set
* @param roundingMode
* the rounding mode to apply if rounding is necessary
* @return {@code this} Decimal after assigning: round(value)
* @throws IllegalArgumentException
* if {@code value} is too large to be represented as a Decimal
* with the scale of this mutable Decimal
* @throws ArithmeticException
* if {@code roundingMode} is {@link RoundingMode#UNNECESSARY
* UNNESSESSARY} and rounding is necessary
*/
MutableDecimal set(BigDecimal value, RoundingMode roundingMode);
/**
* Sets {@code this} Decimal to the specified {@code unscaledValue} and
* returns {@code this} now representing (unscaledValue * 10
* -scale) where scale refers to the {@link #getScale()
* scale} of this mutable Decimal.
*
* @param unscaledValue
* value to be set
* @return {@code this} Decimal after assigning:
* unscaledValue * 10-scale.
*/
MutableDecimal setUnscaled(long unscaledValue);
/**
* Sets {@code this} Decimal to the specified {@code unscaledValue} with the
* given {@code scale} and returns {@code this} now representing
* (unscaledValue * 10-scale). The value is rounded to
* the {@link #getScale() scale} of this mutable Decimal using
* {@link RoundingMode#HALF_UP HALF_UP} rounding. An exception is thrown if
* the specified value is too large to be represented as a Decimal of this
* of this mutable Decimal's scale.
*
* @param unscaledValue
* value to be set
* @param scale
* the scale used for {@code unscaledValue}
* @return {@code this} Decimal after assigning:
* roundHALF_UP(unscaledValue * 10-scale)
* @throws IllegalArgumentException
* if the value is too large to be represented as a Decimal with
* the scale of this mutable Decimal
*/
MutableDecimal setUnscaled(long unscaledValue, int scale);
/**
* Sets {@code this} Decimal to the specified {@code unscaledValue} with the
* given {@code scale} and returns {@code this} now representing
* (unscaledValue * 10-scale). The value is rounded to
* the {@link #getScale() scale} of this mutable Decimal using the specified
* {@code roundingMode}. An exception is thrown if the specified value is
* too large to be represented as a Decimal of this of this mutable
* Decimal's scale.
*
* @param unscaledValue
* value to be set
* @param scale
* the scale used for {@code unscaledValue}
* @param roundingMode
* the rounding mode to apply during the conversion if necessary
* @return {@code this} Decimal after assigning:
* round(unscaledValue * 10-scale)
* @throws IllegalArgumentException
* if the value is too large to be represented as a Decimal with
* the scale of this mutable Decimal
* @throws ArithmeticException
* if {@code roundingMode} is {@link RoundingMode#UNNECESSARY
* UNNESSESSARY} and rounding is necessary
*/
MutableDecimal setUnscaled(long unscaledValue, int scale, RoundingMode roundingMode);
/**
* Parses the given string value and sets {@code this} Decimal to the parsed
* {@code value}.
*
* The string representation of a {@code Decimal} consists of an optional
* sign, {@code '+'} or {@code '-'} , followed by a sequence of zero or more
* decimal digits ("the integer"), optionally followed by a fraction.
*
* The fraction consists of a decimal point followed by zero or more decimal
* digits. The string must contain at least one digit in either the integer
* or the fraction. If the fraction contains more digits than this mutable
* Decimal's {@link #getScale() scale}, the value is rounded using
* {@link RoundingMode#HALF_UP HALF_UP} rounding. An exception is thrown if
* the value is too large to be represented as a Decimal of this mutable
* Decimals's scale.
*
* @param value
* the string value to parse and assign
* @return {@code this} Decimal after assigning the parsed value
* @throws NumberFormatException
* if {@code value} does not represent a valid {@code Decimal}
* or if the value is too large to be represented as a Decimal
* with the scale of this mutable Decimal's scale
*/
MutableDecimal set(String value);
/**
* Parses the given string value and sets {@code this} Decimal to the parsed
* {@code value}.
*
* The string representation of a {@code Decimal} consists of an optional
* sign, {@code '+'} or {@code '-'} , followed by a sequence of zero or more
* decimal digits ("the integer"), optionally followed by a fraction.
*
* The fraction consists of a decimal point followed by zero or more decimal
* digits. The string must contain at least one digit in either the integer
* or the fraction. If the fraction contains more digits than this mutable
* Decimal's {@link #getScale() scale}, the value is rounded using the
* specified {@code roundingMode}. An exception is thrown if the value is
* too large to be represented as a Decimal of this mutable Decimals's
* scale.
*
* @param value
* the string value to parse and assign
* @param roundingMode
* the rounding mode to apply if the fraction contains more
* digits than the scale of this mutable Decimal
* @return {@code this} Decimal after assigning the parsed value
* @throws NumberFormatException
* if {@code value} does not represent a valid {@code Decimal}
* or if the value is too large to be represented as a Decimal
* with the scale of this mutable Decimal's scale
* @throws ArithmeticException
* if {@code roundingMode==UNNECESSARY} and rounding is
* necessary
*/
MutableDecimal set(String value, RoundingMode roundingMode);
/**
* Returns the minimum of this {@code Decimal} and {@code val}.
*
* @param val
* value with which the minimum is to be computed.
* @return the {@code Decimal} whose value is the lesser of this
* {@code Decimal} and {@code val}. If they are equal, as defined by
* the {@link #compareTo(Decimal) compareTo} method, {@code this} is
* returned.
* @see #compareTo(Decimal)
*/
MutableDecimal min(MutableDecimal val);
/**
* Returns the maximum of this {@code Decimal} and {@code val}.
*
* @param val
* value with which the maximum is to be computed.
* @return the {@code Decimal} whose value is the greater of this
* {@code Decimal} and {@code val}. If they are equal, as defined by
* the {@link #compareTo(Decimal) compareTo} method, {@code this} is
* returned.
* @see #compareTo(Decimal)
*/
MutableDecimal max(MutableDecimal val);
/**
* Returns a clone of this mutable Decimal numerically identical to this
* value.
*
* @return a numerically identical clone of this value
*/
MutableDecimal clone();
// override some methods with specialized return type
@Override
MutableDecimal integralPart();
@Override
MutableDecimal fractionalPart();
@Override
MutableDecimal round(int precision);
@Override
MutableDecimal round(int precision, RoundingMode roundingMode);
@Override
MutableDecimal round(int precision, TruncationPolicy truncationPolicy);
@Override
MutableDecimal scale(int scale);
@SuppressWarnings("hiding")
@Override
MutableDecimal scale(S scaleMetrics);
@Override
MutableDecimal scale(int scale, RoundingMode roundingMode);
@SuppressWarnings("hiding")
@Override
MutableDecimal scale(S scaleMetrics, RoundingMode roundingMode);
@Override
MutableDecimal add(Decimal augend);
@Override
MutableDecimal add(Decimal augend, OverflowMode overflowMode);
@Override
MutableDecimal add(Decimal augend, RoundingMode roundingMode);
@Override
MutableDecimal add(Decimal augend, TruncationPolicy truncationPolicy);
@Override
MutableDecimal add(long augend);
@Override
MutableDecimal add(long augend, OverflowMode overflowMode);
@Override
MutableDecimal add(double augend);
@Override
MutableDecimal add(double augend, RoundingMode roundingMode);
@Override
MutableDecimal addUnscaled(long unscaledAugend);
@Override
MutableDecimal addUnscaled(long unscaledAugend, OverflowMode overflowMode);
@Override
MutableDecimal addUnscaled(long unscaledAugend, int scale);
@Override
MutableDecimal addUnscaled(long unscaledAugend, int scale, RoundingMode roundingMode);
@Override
MutableDecimal addUnscaled(long unscaledAugend, int scale, TruncationPolicy truncationPolicy);
@Override
MutableDecimal addSquared(Decimal value);
@Override
MutableDecimal addSquared(Decimal value, RoundingMode roundingMode);
@Override
MutableDecimal addSquared(Decimal value, TruncationPolicy truncationPolicy);
@Override
MutableDecimal subtract(Decimal subtrahend);
@Override
MutableDecimal subtract(Decimal subtrahend, OverflowMode overflowMode);
@Override
MutableDecimal subtract(Decimal subtrahend, RoundingMode roundingMode);
@Override
MutableDecimal subtract(Decimal subtrahend, TruncationPolicy truncationPolicy);
@Override
MutableDecimal subtract(long subtrahend);
@Override
MutableDecimal subtract(long subtrahend, OverflowMode overflowMode);
@Override
MutableDecimal subtract(double subtrahend);
@Override
MutableDecimal subtract(double subtrahend, RoundingMode roundingMode);
@Override
MutableDecimal subtractUnscaled(long unscaledSubtrahend);
@Override
MutableDecimal subtractUnscaled(long unscaledSubtrahend, OverflowMode overflowMode);
@Override
MutableDecimal subtractUnscaled(long unscaledSubtrahend, int scale);
@Override
MutableDecimal subtractUnscaled(long unscaledSubtrahend, int scale, RoundingMode roundingMode);
@Override
MutableDecimal subtractUnscaled(long unscaledSubtrahend, int scale, TruncationPolicy truncationPolicy);
@Override
MutableDecimal subtractSquared(Decimal value);
@Override
MutableDecimal subtractSquared(Decimal value, RoundingMode roundingMode);
@Override
MutableDecimal subtractSquared(Decimal value, TruncationPolicy truncationPolicy);
@Override
MutableDecimal multiply(Decimal multiplicand);
@Override
MutableDecimal multiply(Decimal multiplicand, RoundingMode roundingMode);
@Override
MutableDecimal multiply(Decimal multiplicand, TruncationPolicy truncationPolicy);
@Override
MutableDecimal multiplyBy(Decimal multiplicand);
@Override
MutableDecimal multiplyBy(Decimal multiplicand, RoundingMode roundingMode);
@Override
MutableDecimal multiplyBy(Decimal multiplicand, TruncationPolicy truncationPolicy);
@Override
MutableDecimal multiplyExact(Decimal multiplicand);
@Override
MutableDecimal multiply(long multiplicand);
@Override
MutableDecimal multiply(long multiplicand, OverflowMode overflowMode);
@Override
MutableDecimal multiply(double multiplicand);
@Override
MutableDecimal multiply(double multiplicand, RoundingMode roundingMode);
@Override
MutableDecimal multiplyUnscaled(long unscaledMultiplicand);
@Override
MutableDecimal multiplyUnscaled(long unscaledMultiplicand, RoundingMode roundingMode);
@Override
MutableDecimal multiplyUnscaled(long unscaledMultiplicand, TruncationPolicy truncationPolicy);
@Override
MutableDecimal multiplyUnscaled(long unscaledMultiplicand, int scale);
@Override
MutableDecimal multiplyUnscaled(long unscaledMultiplicand, int scale, RoundingMode roundingMode);
@Override
MutableDecimal multiplyUnscaled(long unscaledMultiplicand, int scale, TruncationPolicy truncationPolicy);
@Override
MutableDecimal multiplyByPowerOfTen(int n);
@Override
MutableDecimal multiplyByPowerOfTen(int n, RoundingMode roundingMode);
@Override
MutableDecimal multiplyByPowerOfTen(int n, TruncationPolicy truncationPolicy);
@Override
MutableDecimal divide(Decimal divisor);
@Override
MutableDecimal divide(Decimal divisor, RoundingMode roundingMode);
@Override
MutableDecimal divide(Decimal divisor, TruncationPolicy truncationPolicy);
@Override
MutableDecimal divideBy(Decimal divisor);
@Override
MutableDecimal divideBy(Decimal divisor, RoundingMode roundingMode);
@Override
MutableDecimal divideBy(Decimal divisor, TruncationPolicy truncationPolicy);
@Override
MutableDecimal divideTruncate(Decimal divisor);
@Override
MutableDecimal divideExact(Decimal divisor);
@Override
MutableDecimal divide(long divisor);
@Override
MutableDecimal divide(long divisor, RoundingMode roundingMode);
@Override
MutableDecimal divide(long divisor, TruncationPolicy truncationPolicy);
@Override
MutableDecimal divide(double divisor);
@Override
MutableDecimal divide(double divisor, RoundingMode roundingMode);
@Override
MutableDecimal divideUnscaled(long unscaledDivisor);
@Override
MutableDecimal divideUnscaled(long unscaledDivisor, RoundingMode roundingMode);
@Override
MutableDecimal divideUnscaled(long unscaledDivisor, TruncationPolicy truncationPolicy);
@Override
MutableDecimal divideUnscaled(long unscaledDivisor, int scale);
@Override
MutableDecimal divideUnscaled(long unscaledDivisor, int scale, RoundingMode roundingMode);
@Override
MutableDecimal divideUnscaled(long unscaledDivisor, int scale, TruncationPolicy truncationPolicy);
@Override
MutableDecimal divideByPowerOfTen(int n);
@Override
MutableDecimal divideByPowerOfTen(int n, RoundingMode roundingMode);
@Override
MutableDecimal divideByPowerOfTen(int n, TruncationPolicy truncationPolicy);
@Override
MutableDecimal divideToIntegralValue(Decimal divisor);
@Override
MutableDecimal divideToIntegralValue(Decimal divisor, OverflowMode overflowMode);
@Override
MutableDecimal[] divideAndRemainder(Decimal divisor);
@Override
MutableDecimal[] divideAndRemainder(Decimal divisor, OverflowMode overflowMode);
@Override
MutableDecimal remainder(Decimal divisor);
@Override
MutableDecimal negate();
@Override
MutableDecimal negate(OverflowMode overflowMode);
@Override
MutableDecimal abs();
@Override
MutableDecimal abs(OverflowMode overflowMode);
@Override
MutableDecimal invert();
@Override
MutableDecimal invert(RoundingMode roundingMode);
@Override
MutableDecimal invert(TruncationPolicy truncationPolicy);
@Override
MutableDecimal square();
@Override
MutableDecimal square(RoundingMode roundingMode);
@Override
MutableDecimal square(TruncationPolicy truncationPolicy);
@Override
MutableDecimal sqrt();
@Override
MutableDecimal sqrt(RoundingMode roundingMode);
@Override
MutableDecimal shiftLeft(int n);
@Override
MutableDecimal shiftLeft(int n, RoundingMode roundingMode);
@Override
MutableDecimal shiftLeft(int n, TruncationPolicy truncationPolicy);
@Override
MutableDecimal shiftRight(int n);
@Override
MutableDecimal shiftRight(int n, RoundingMode roundingMode);
@Override
MutableDecimal shiftRight(int n, TruncationPolicy truncationPolicy);
@Override
MutableDecimal pow(int n);
@Override
MutableDecimal pow(int n, RoundingMode roundingMode);
@Override
MutableDecimal pow(int n, TruncationPolicy truncationPolicy);
@Override
MutableDecimal avg(Decimal val);
@Override
MutableDecimal avg(Decimal val, RoundingMode roundingMode);
}