com.amazon.ion

Class Decimal

java.lang.Object

java.lang.Number

java.math.BigDecimal

com.amazon.ion.Decimal

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<java.math.BigDecimal>

public class Decimal
extends java.math.BigDecimal

An extension of BigDecimal that can represent negative zeros. The primary change is the addition of isNegativeZero().

WARNING: This class should not be extended by code outside of this library.

This class currently does not have any behavioral difference from BigDecimal except for the following:

• BigDecimal.toString(), BigDecimal.toEngineeringString(), and BigDecimal.toPlainString() print a negative sign if necessary.
• BigDecimal.floatValue() and BigDecimal.doubleValue() return negative zero results.
• BigDecimal.abs() does the right thing.

This class does NOT override equals(java.math.BigDecimal, java.math.BigDecimal) or BigDecimal.compareTo(java.math.BigDecimal) so those methods cannot distinguish positive and negative zeros.

It also does not currently override any of the numerical methods, but it may do so in the future. If you are concerned about consistent treatment of negative zeros in future releases, you may wish to use bigDecimalValue(java.math.BigDecimal) before performing those operations.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static Decimal	NEGATIVE_ZERO The value -0, with a scale of 0.
static Decimal	ZERO The value 0, with a scale of 0.

Fields inherited from class java.math.BigDecimal

ONE, ROUND_CEILING, ROUND_DOWN, ROUND_FLOOR, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_HALF_UP, ROUND_UNNECESSARY, ROUND_UP, TEN

Method Summary

Modifier and Type	Method and Description
java.math.BigDecimal	bigDecimalValue() Converts this to a "plain" BigDecimal instance, losing any negative zeros in the process.
static java.math.BigDecimal	bigDecimalValue(java.math.BigDecimal val) Returns a "plain" BigDecimal instance, never a Decimal subclass.
static boolean	equals(java.math.BigDecimal v1, java.math.BigDecimal v2) Compares two decimal values for equality, observing both precision and negative zeros.
boolean	isNegativeZero()
static boolean	isNegativeZero(java.math.BigDecimal val) Efficiently determines whether an arbitary decimal value is a negative zero.
static Decimal	negativeZero(int scale) Returns a negative-zero decimal value, with the given number of significant digits (zeros).
static Decimal	negativeZero(int scale, java.math.MathContext mc) Returns a negative-zero decimal value, with the given number of significant digits (zeros) and given context.
static Decimal	valueOf(java.math.BigDecimal val)
static Decimal	valueOf(java.math.BigDecimal val, java.math.MathContext mc)
static Decimal	valueOf(java.math.BigInteger val)
static Decimal	valueOf(java.math.BigInteger unscaledVal, int scale)
static Decimal	valueOf(java.math.BigInteger unscaledVal, int scale, java.math.MathContext mc)
static Decimal	valueOf(java.math.BigInteger val, java.math.MathContext mc)
static Decimal	valueOf(double val)
static Decimal	valueOf(double val, java.math.MathContext mc)
static Decimal	valueOf(int val)
static Decimal	valueOf(int val, java.math.MathContext mc)
static Decimal	valueOf(long val)
static Decimal	valueOf(long val, java.math.MathContext mc)
static Decimal	valueOf(java.lang.String val)
static Decimal	valueOf(java.lang.String val, java.math.MathContext mc)

Methods inherited from class java.math.BigDecimal

abs, abs, add, add, byteValueExact, compareTo, divide, divide, divide, divide, divide, divide, divideAndRemainder, divideAndRemainder, divideToIntegralValue, divideToIntegralValue, doubleValue, equals, floatValue, hashCode, intValue, intValueExact, longValue, longValueExact, max, min, movePointLeft, movePointRight, multiply, multiply, negate, negate, plus, plus, pow, pow, precision, remainder, remainder, round, scale, scaleByPowerOfTen, setScale, setScale, setScale, shortValueExact, signum, stripTrailingZeros, subtract, subtract, toBigInteger, toBigIntegerExact, toEngineeringString, toPlainString, toString, ulp, unscaledValue, valueOf

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ZERO

public static final Decimal ZERO

The value 0, with a scale of 0.

NEGATIVE_ZERO

public static final Decimal NEGATIVE_ZERO

The value -0, with a scale of 0.

Method Detail

isNegativeZero

public static boolean isNegativeZero(java.math.BigDecimal val)

Efficiently determines whether an arbitary decimal value is a negative zero. This can only be true when the value is actually a Decimal.

Returns:

true if and only if the value is a negative zero.

Throws:

java.lang.NullPointerException - if the value is null.

bigDecimalValue

public static java.math.BigDecimal bigDecimalValue(java.math.BigDecimal val)

Returns a "plain" BigDecimal instance, never a Decimal subclass. As a side effect, this strips any negative-zero information.

Parameters:

val - may be null.

Returns:

null if the given value is null.

equals

public static boolean equals(java.math.BigDecimal v1,
                             java.math.BigDecimal v2)

Compares two decimal values for equality, observing both precision and negative zeros. This differs from BigDecimal.equals(Object), which isn't aware of negative zeros, and from BigDecimal.compareTo(BigDecimal), which ignores both precision and negative zeros.

Returns:

true if and only if the two BigDecimal objects have the same value, scale, and sign.

Throws:

java.lang.NullPointerException - if either parameter is null.

negativeZero

public static Decimal negativeZero(int scale)

Returns a negative-zero decimal value, with the given number of significant digits (zeros).

Parameters:

scale - the number of significant digits (zeros) after the decimal point.

negativeZero

public static Decimal negativeZero(int scale,
                                   java.math.MathContext mc)

Returns a negative-zero decimal value, with the given number of significant digits (zeros) and given context.

Parameters:

scale - the number of significant digits (zeros) after the decimal point.

valueOf

public static Decimal valueOf(java.math.BigInteger unscaledVal,
                              int scale)

valueOf

public static Decimal valueOf(java.math.BigInteger unscaledVal,
                              int scale,
                              java.math.MathContext mc)

valueOf

public static Decimal valueOf(java.math.BigInteger val)

valueOf

public static Decimal valueOf(java.math.BigInteger val,
                              java.math.MathContext mc)

valueOf

public static Decimal valueOf(int val)

valueOf

public static Decimal valueOf(int val,
                              java.math.MathContext mc)

valueOf

public static Decimal valueOf(long val)

valueOf

public static Decimal valueOf(long val,
                              java.math.MathContext mc)

valueOf

public static Decimal valueOf(double val)

valueOf

public static Decimal valueOf(double val,
                              java.math.MathContext mc)

valueOf

public static Decimal valueOf(java.math.BigDecimal val)

valueOf

public static Decimal valueOf(java.math.BigDecimal val,
                              java.math.MathContext mc)

valueOf

public static Decimal valueOf(java.lang.String val)

valueOf

public static Decimal valueOf(java.lang.String val,
                              java.math.MathContext mc)

isNegativeZero

public final boolean isNegativeZero()

bigDecimalValue

public final java.math.BigDecimal bigDecimalValue()

Converts this to a "plain" BigDecimal instance, losing any negative zeros in the process.

Returns:

a BigDecimal, never a Decimal.