com.programix.math
Class DecimalTools

java.lang.Object
  com.programix.math.DecimalTools

public class DecimalTools
extends Object

Field Summary

static BigDecimal	EIGHT
static BigDecimal	EIGHTEEN
static BigDecimal	EIGHTY
static BigDecimal	EIGHTY_EIGHT
static BigDecimal	EIGHTY_FIVE
static BigDecimal	EIGHTY_FOUR
static BigDecimal	EIGHTY_NINE
static BigDecimal	EIGHTY_ONE
static BigDecimal	EIGHTY_SEVEN
static BigDecimal	EIGHTY_SIX
static BigDecimal	EIGHTY_THREE
static BigDecimal	EIGHTY_TWO
static BigDecimal	ELEVEN
static BigDecimal	FIFTEEN
static BigDecimal	FIFTY
static BigDecimal	FIFTY_EIGHT
static BigDecimal	FIFTY_FIVE
static BigDecimal	FIFTY_FOUR
static BigDecimal	FIFTY_NINE
static BigDecimal	FIFTY_ONE
static BigDecimal	FIFTY_SEVEN
static BigDecimal	FIFTY_SIX
static BigDecimal	FIFTY_THREE
static BigDecimal	FIFTY_TWO
static BigDecimal	FIVE
static BigDecimal	FORTY
static BigDecimal	FORTY_EIGHT
static BigDecimal	FORTY_FIVE
static BigDecimal	FORTY_FOUR
static BigDecimal	FORTY_NINE
static BigDecimal	FORTY_ONE
static BigDecimal	FORTY_SEVEN
static BigDecimal	FORTY_SIX
static BigDecimal	FORTY_THREE
static BigDecimal	FORTY_TWO
static BigDecimal	FOUR
static BigDecimal	FOURTEEN
static char	GROUPING_CHAR_COMMA The character ',' (comma).
static char	GROUPING_CHAR_NONE Used to indicate that "thousands" should not be separated by any character at all (no grouping).
static BigDecimal	NEGATIVE_ONE Equal to: -1
static BigDecimal	NINE
static BigDecimal	NINETEEN
static BigDecimal	NINETY
static BigDecimal	NINETY_EIGHT
static BigDecimal	NINETY_FIVE
static BigDecimal	NINETY_FOUR
static BigDecimal	NINETY_NINE
static BigDecimal	NINETY_ONE
static BigDecimal	NINETY_SEVEN
static BigDecimal	NINETY_SIX
static BigDecimal	NINETY_THREE
static BigDecimal	NINETY_TWO
static BigDecimal	ONE
static BigDecimal	ONE_BILLION
static BigDecimal	ONE_EIGHTH Equal to: 0.125 (3 decimal places)
static BigDecimal	ONE_ELEVENTH Equal to: 0.0909090909090909090909091 (25 decimal places)
static BigDecimal	ONE_FIFTH Equal to: 0.2 (1 decimal place)
static BigDecimal	ONE_FOURTH Alternate name for ONE_QUARTER
static BigDecimal	ONE_HALF Equal to: 0.5 (1 decimal place)
static BigDecimal	ONE_HUNDRED
static BigDecimal	ONE_HUNDRED_BILLION
static BigDecimal	ONE_HUNDRED_MILLION
static BigDecimal	ONE_HUNDRED_THOUSAND
static BigDecimal	ONE_HUNDREDTH Equal to: 0.01 (2 decimal places)
static BigDecimal	ONE_MILLION
static BigDecimal	ONE_MILLIONTH Equal to: 0.00001 (5 decimal places)
static BigDecimal	ONE_NINTH Equal to: 0.1111111111111111111111111 (25 decimal places)
static BigDecimal	ONE_QUARTER Equal to: 0.25 (2 decimal places)
static BigDecimal	ONE_SEVENTH Equal to: 0.1428571428571428571428571 (25 decimal places)
static BigDecimal	ONE_SIXTEENTH Equal to: 0.0625 (4 decimal places)
static BigDecimal	ONE_SIXTH Equal to: 0.1666666666666666666666667 (25 decimal places)
static BigDecimal	ONE_TEN_THOUSANDTH Equal to: 0.0001 (4 decimal places)
static BigDecimal	ONE_TENTH Equal to: 0.1 (1 decimal place)
static BigDecimal	ONE_THIRD Equal to: 0.3333333333333333333333333 (25 decimal places)
static BigDecimal	ONE_THOUSAND
static BigDecimal	ONE_THOUSANDTH Equal to: 0.001 (3 decimal places)
static BigDecimal	ONE_TRILLION
static BigDecimal	ONE_TWELFTH Equal to: 0.0833333333333333333333333 (25 decimal places)
static char	PAD_CHAR_NONE Used to indicate that there should not be any any padding done at all.
static char	PAD_CHAR_SPACE The character ' ' (space).
static char	PAD_CHAR_ZERO The character '0' (zero).
static BigDecimal	SEVEN
static BigDecimal	SEVENTEEN
static BigDecimal	SEVENTY
static BigDecimal	SEVENTY_EIGHT
static BigDecimal	SEVENTY_FIVE
static BigDecimal	SEVENTY_FOUR
static BigDecimal	SEVENTY_NINE
static BigDecimal	SEVENTY_ONE
static BigDecimal	SEVENTY_SEVEN
static BigDecimal	SEVENTY_SIX
static BigDecimal	SEVENTY_THREE
static BigDecimal	SEVENTY_TWO
static BigDecimal	SIX
static BigDecimal	SIXTEEN
static BigDecimal	SIXTY
static BigDecimal	SIXTY_EIGHT
static BigDecimal	SIXTY_FIVE
static BigDecimal	SIXTY_FOUR
static BigDecimal	SIXTY_NINE
static BigDecimal	SIXTY_ONE
static BigDecimal	SIXTY_SEVEN
static BigDecimal	SIXTY_SIX
static BigDecimal	SIXTY_THREE
static BigDecimal	SIXTY_TWO
static BigDecimal	TEN
static BigDecimal	TEN_BILLION
static BigDecimal	TEN_MILLION
static BigDecimal	TEN_THOUSAND
static BigDecimal	THIRTEEN
static BigDecimal	THIRTY
static BigDecimal	THIRTY_EIGHT
static BigDecimal	THIRTY_FIVE
static BigDecimal	THIRTY_FOUR
static BigDecimal	THIRTY_NINE
static BigDecimal	THIRTY_ONE
static BigDecimal	THIRTY_SEVEN
static BigDecimal	THIRTY_SIX
static BigDecimal	THIRTY_THREE
static BigDecimal	THIRTY_TWO
static BigDecimal	THREE
static BigDecimal	TWELVE
static BigDecimal	TWENTY
static BigDecimal	TWENTY_EIGHT
static BigDecimal	TWENTY_FIVE
static BigDecimal	TWENTY_FOUR
static BigDecimal	TWENTY_NINE
static BigDecimal	TWENTY_ONE
static BigDecimal	TWENTY_SEVEN
static BigDecimal	TWENTY_SIX
static BigDecimal	TWENTY_THREE
static BigDecimal	TWENTY_TWO
static BigDecimal	TWO
static BigDecimal	ZERO
static BigDecimal[]	ZERO_LEN_ARRAY An array of BigDecimal with a length of zero.

Method Summary

static BigDecimal	convert(int value) Converts the specified value to a BigDecimal returning one of the shared, common, immutable instances if possible.
static BigDecimal	convert(long value) Converts the specified value to a BigDecimal returning one of the shared, common, immutable instances if possible.
static BigDecimal	convert(Number value) Converts the specified value to a BigDecimal returning one of the shared, common, immutable instances if possible.
static boolean	equalTo(BigDecimal a, BigDecimal b) Returns true if a is numerically equal to b (with no regard to scale).
static String	format(BigDecimal value, int integerDigitCount, char integerPaddingChar, int fractionalDigitCount, char fractionalPaddingChar, char thousandGroupingChar)
static String	format(BigDecimal value, int integerDigitCount, int fractionalDigitCount)
static BigDecimal	getMaxValueFor(int integerDigitCount, int fractionalDigitCount) Returns the largest positive value than can fit into the specified number of integer and fractional digits (all nines).
static BigDecimal	getMinValueFor(int integerDigitCount, int fractionalDigitCount) Returns the most negative value than can fit into the specified number of integer and fractional digits (all nines preceded by a minus sign).
static boolean	greaterThan(BigDecimal a, BigDecimal b) Returns true if a is numerically greater than b (with no regard to scale).
static boolean	greaterThanOrEqualTo(BigDecimal a, BigDecimal b) Returns true if a is numerically greater than or equal to b (with no regard to scale).
static boolean	isDifferent(BigDecimal a, BigDecimal b) Compares two BigDecimals to see if they are "different" (without regard to the scales of each one).
static boolean	isEmpty(BigDecimal val) Returns true if the specified BigDecimal is either null or zero.
static boolean	isNegative(BigDecimal val) Returns true if val is negative (numerically less than ZERO).
static boolean	isNotEmpty(BigDecimal val) Returns true if the specified BigDecimal is not null and is not equal to zero.
static boolean	isNotNegative(BigDecimal val) Returns true if val is non-negative (numerically greater than or equal to ZERO).
static boolean	isNotPositive(BigDecimal val) Returns true if val is non-positive (numerically less than or equal to ZERO).
static boolean	isNotZero(BigDecimal val) Returns true if val is numerically not equal to ZERO (with no regard to scale).
static boolean	isPositive(BigDecimal val) Returns true if val is positive (numerically greater than ZERO).
static boolean	isSame(BigDecimal a, BigDecimal b) Compares two BigDecimals to see if they are the "same" (without regard to the scales of each one).
static boolean	isZero(BigDecimal val) Returns true if val is numerically equal to ZERO (with no regard to scale).
static boolean	lessThan(BigDecimal a, BigDecimal b) Returns true if a is numerically less than b (with no regard to scale).
static boolean	lessThanOrEqualTo(BigDecimal a, BigDecimal b) Returns true if a is numerically less than or equal to b (with no regard to scale).
static BigDecimal	max(BigDecimal a, BigDecimal b) Returns the numerically larger of a and b (with no regard to scale).
static BigDecimal	max(BigDecimal a, BigDecimal b, BigDecimal c) Returns the numerically largest of a, b and c (with no regard to scale).
static BigDecimal	min(BigDecimal a, BigDecimal b) Returns the numerically smaller of a and b (with no regard to scale).
static BigDecimal	min(BigDecimal a, BigDecimal b, BigDecimal c) Returns the numerically smallest of a, b and c (with no regard to scale).
static boolean	notEqualTo(BigDecimal a, BigDecimal b) Returns true if a is numerically not equal to b (with no regard to scale).
static boolean	notGreaterThan(BigDecimal a, BigDecimal b) Returns true if a is numerically not greater than b (with no regard to scale).
static boolean	notLessThan(BigDecimal a, BigDecimal b) Returns true if a is numerically not less than b (with no regard to scale).
static BigDecimal	parseBigDecimal(String source) Permissively parses the passed String into a BigDecimal.
static BigDecimal	parseBigDecimal(String source, BigDecimal defaultValue) Permissively parses the passed String into a BigDecimal.
static double	parseDouble(String source) Permissively parses the passed String into a double.
static double	parseDouble(String source, double defaultValue) Permissively parses the passed String into a double.
static Value	parseValue(String source) Permissively parses the passed String into a Value that if not empty, wraps an instance of BigDecimal.
static BigDecimal	rangeBound(BigDecimal minValue, BigDecimal value, BigDecimal maxValue) Bounds value to the specified range.
static BigDecimal	round(BigDecimal value) Rounds to the nearest 1 (nearest integer).
static BigDecimal	round(BigDecimal value, BigDecimal nearest) Equivalent to: round(value, nearest, BigDecimal.ROUND_HALF_UP)
static BigDecimal	round(BigDecimal value, BigDecimal nearest, int roundingMode) Returns value rounded to the nearest multiple of the specified value nearest.
static BigDecimal	roundDollar(BigDecimal value) Same as round(BigDecimal) (nearest integer).
static BigDecimal	roundEighth(BigDecimal value) Rounds to the nearest 1/8 (multiple of 0.125).
static BigDecimal	roundHalf(BigDecimal value) Rounds to the nearest 1/2 (multiple of 0.5).
static BigDecimal	roundHundredth(BigDecimal value) Rounds to the nearest 0.01.
static BigDecimal	roundPenny(BigDecimal value) Same as roundHundredth(BigDecimal).
static BigDecimal	roundQuarter(BigDecimal value) Rounds to the nearest 1/4 (multiple of 0.25).
static BigDecimal	roundSixteenth(BigDecimal value) Rounds to the nearest 1/16 (multiple of 0.0625).
static BigDecimal	roundTenth(BigDecimal value) Rounds to the nearest 0.1.
static BigDecimal	roundThousandth(BigDecimal value) Rounds to the nearest 0.001.
static BigDecimal	sum(BigDecimal[] val) Returns the sum of all of the values in the array passed in.
static BigDecimal[]	toArray(Collection<BigDecimal> bigDecimals)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ZERO

public static final BigDecimal ZERO

ONE

public static final BigDecimal ONE

TWO

public static final BigDecimal TWO

THREE

public static final BigDecimal THREE

FOUR

public static final BigDecimal FOUR

FIVE

public static final BigDecimal FIVE

SIX

public static final BigDecimal SIX

SEVEN

public static final BigDecimal SEVEN

EIGHT

public static final BigDecimal EIGHT

NINE

public static final BigDecimal NINE

TEN

public static final BigDecimal TEN

ELEVEN

public static final BigDecimal ELEVEN

TWELVE

public static final BigDecimal TWELVE

THIRTEEN

public static final BigDecimal THIRTEEN

FOURTEEN

public static final BigDecimal FOURTEEN

FIFTEEN

public static final BigDecimal FIFTEEN

SIXTEEN

public static final BigDecimal SIXTEEN

SEVENTEEN

public static final BigDecimal SEVENTEEN

EIGHTEEN

public static final BigDecimal EIGHTEEN

NINETEEN

public static final BigDecimal NINETEEN

TWENTY

public static final BigDecimal TWENTY

TWENTY_ONE

public static final BigDecimal TWENTY_ONE

TWENTY_TWO

public static final BigDecimal TWENTY_TWO

TWENTY_THREE

public static final BigDecimal TWENTY_THREE

TWENTY_FOUR

public static final BigDecimal TWENTY_FOUR

TWENTY_FIVE

public static final BigDecimal TWENTY_FIVE

TWENTY_SIX

public static final BigDecimal TWENTY_SIX

TWENTY_SEVEN

public static final BigDecimal TWENTY_SEVEN

TWENTY_EIGHT

public static final BigDecimal TWENTY_EIGHT

TWENTY_NINE

public static final BigDecimal TWENTY_NINE

THIRTY

public static final BigDecimal THIRTY

THIRTY_ONE

public static final BigDecimal THIRTY_ONE

THIRTY_TWO

public static final BigDecimal THIRTY_TWO

THIRTY_THREE

public static final BigDecimal THIRTY_THREE

THIRTY_FOUR

public static final BigDecimal THIRTY_FOUR

THIRTY_FIVE

public static final BigDecimal THIRTY_FIVE

THIRTY_SIX

public static final BigDecimal THIRTY_SIX

THIRTY_SEVEN

public static final BigDecimal THIRTY_SEVEN

THIRTY_EIGHT

public static final BigDecimal THIRTY_EIGHT

THIRTY_NINE

public static final BigDecimal THIRTY_NINE

FORTY

public static final BigDecimal FORTY

FORTY_ONE

public static final BigDecimal FORTY_ONE

FORTY_TWO

public static final BigDecimal FORTY_TWO

FORTY_THREE

public static final BigDecimal FORTY_THREE

FORTY_FOUR

public static final BigDecimal FORTY_FOUR

FORTY_FIVE

public static final BigDecimal FORTY_FIVE

FORTY_SIX

public static final BigDecimal FORTY_SIX

FORTY_SEVEN

public static final BigDecimal FORTY_SEVEN

FORTY_EIGHT

public static final BigDecimal FORTY_EIGHT

FORTY_NINE

public static final BigDecimal FORTY_NINE

FIFTY

public static final BigDecimal FIFTY

FIFTY_ONE

public static final BigDecimal FIFTY_ONE

FIFTY_TWO

public static final BigDecimal FIFTY_TWO

FIFTY_THREE

public static final BigDecimal FIFTY_THREE

FIFTY_FOUR

public static final BigDecimal FIFTY_FOUR

FIFTY_FIVE

public static final BigDecimal FIFTY_FIVE

FIFTY_SIX

public static final BigDecimal FIFTY_SIX

FIFTY_SEVEN

public static final BigDecimal FIFTY_SEVEN

FIFTY_EIGHT

public static final BigDecimal FIFTY_EIGHT

FIFTY_NINE

public static final BigDecimal FIFTY_NINE

SIXTY

public static final BigDecimal SIXTY

SIXTY_ONE

public static final BigDecimal SIXTY_ONE

SIXTY_TWO

public static final BigDecimal SIXTY_TWO

SIXTY_THREE

public static final BigDecimal SIXTY_THREE

SIXTY_FOUR

public static final BigDecimal SIXTY_FOUR

SIXTY_FIVE

public static final BigDecimal SIXTY_FIVE

SIXTY_SIX

public static final BigDecimal SIXTY_SIX

SIXTY_SEVEN

public static final BigDecimal SIXTY_SEVEN

SIXTY_EIGHT

public static final BigDecimal SIXTY_EIGHT

SIXTY_NINE

public static final BigDecimal SIXTY_NINE

SEVENTY

public static final BigDecimal SEVENTY

SEVENTY_ONE

public static final BigDecimal SEVENTY_ONE

SEVENTY_TWO

public static final BigDecimal SEVENTY_TWO

SEVENTY_THREE

public static final BigDecimal SEVENTY_THREE

SEVENTY_FOUR

public static final BigDecimal SEVENTY_FOUR

SEVENTY_FIVE

public static final BigDecimal SEVENTY_FIVE

SEVENTY_SIX

public static final BigDecimal SEVENTY_SIX

SEVENTY_SEVEN

public static final BigDecimal SEVENTY_SEVEN

SEVENTY_EIGHT

public static final BigDecimal SEVENTY_EIGHT

SEVENTY_NINE

public static final BigDecimal SEVENTY_NINE

EIGHTY

public static final BigDecimal EIGHTY

EIGHTY_ONE

public static final BigDecimal EIGHTY_ONE

EIGHTY_TWO

public static final BigDecimal EIGHTY_TWO

EIGHTY_THREE

public static final BigDecimal EIGHTY_THREE

EIGHTY_FOUR

public static final BigDecimal EIGHTY_FOUR

EIGHTY_FIVE

public static final BigDecimal EIGHTY_FIVE

EIGHTY_SIX

public static final BigDecimal EIGHTY_SIX

EIGHTY_SEVEN

public static final BigDecimal EIGHTY_SEVEN

EIGHTY_EIGHT

public static final BigDecimal EIGHTY_EIGHT

EIGHTY_NINE

public static final BigDecimal EIGHTY_NINE

NINETY

public static final BigDecimal NINETY

NINETY_ONE

public static final BigDecimal NINETY_ONE

NINETY_TWO

public static final BigDecimal NINETY_TWO

NINETY_THREE

public static final BigDecimal NINETY_THREE

NINETY_FOUR

public static final BigDecimal NINETY_FOUR

NINETY_FIVE

public static final BigDecimal NINETY_FIVE

NINETY_SIX

public static final BigDecimal NINETY_SIX

NINETY_SEVEN

public static final BigDecimal NINETY_SEVEN

NINETY_EIGHT

public static final BigDecimal NINETY_EIGHT

NINETY_NINE

public static final BigDecimal NINETY_NINE

ONE_HUNDRED

public static final BigDecimal ONE_HUNDRED

ONE_THOUSAND

public static final BigDecimal ONE_THOUSAND

TEN_THOUSAND

public static final BigDecimal TEN_THOUSAND

ONE_HUNDRED_THOUSAND

public static final BigDecimal ONE_HUNDRED_THOUSAND

ONE_MILLION

public static final BigDecimal ONE_MILLION

TEN_MILLION

public static final BigDecimal TEN_MILLION

ONE_HUNDRED_MILLION

public static final BigDecimal ONE_HUNDRED_MILLION

ONE_BILLION

public static final BigDecimal ONE_BILLION

TEN_BILLION

public static final BigDecimal TEN_BILLION

ONE_HUNDRED_BILLION

public static final BigDecimal ONE_HUNDRED_BILLION

ONE_TRILLION

public static final BigDecimal ONE_TRILLION

ONE_HALF

public static final BigDecimal ONE_HALF

Equal to: 0.5 (1 decimal place)

ONE_THIRD

public static final BigDecimal ONE_THIRD

Equal to: 0.3333333333333333333333333 (25 decimal places)

ONE_QUARTER

public static final BigDecimal ONE_QUARTER

Equal to: 0.25 (2 decimal places)

ONE_FOURTH

public static final BigDecimal ONE_FOURTH

Alternate name for ONE_QUARTER

ONE_FIFTH

public static final BigDecimal ONE_FIFTH

Equal to: 0.2 (1 decimal place)

ONE_SIXTH

public static final BigDecimal ONE_SIXTH

Equal to: 0.1666666666666666666666667 (25 decimal places)

ONE_SEVENTH

public static final BigDecimal ONE_SEVENTH

Equal to: 0.1428571428571428571428571 (25 decimal places)

ONE_EIGHTH

public static final BigDecimal ONE_EIGHTH

Equal to: 0.125 (3 decimal places)

ONE_NINTH

public static final BigDecimal ONE_NINTH

Equal to: 0.1111111111111111111111111 (25 decimal places)

ONE_TENTH

public static final BigDecimal ONE_TENTH

Equal to: 0.1 (1 decimal place)

ONE_ELEVENTH

public static final BigDecimal ONE_ELEVENTH

Equal to: 0.0909090909090909090909091 (25 decimal places)

ONE_TWELFTH

public static final BigDecimal ONE_TWELFTH

Equal to: 0.0833333333333333333333333 (25 decimal places)

ONE_SIXTEENTH

public static final BigDecimal ONE_SIXTEENTH

Equal to: 0.0625 (4 decimal places)

ONE_HUNDREDTH

public static final BigDecimal ONE_HUNDREDTH

Equal to: 0.01 (2 decimal places)

ONE_THOUSANDTH

public static final BigDecimal ONE_THOUSANDTH

Equal to: 0.001 (3 decimal places)

ONE_TEN_THOUSANDTH

public static final BigDecimal ONE_TEN_THOUSANDTH

Equal to: 0.0001 (4 decimal places)

ONE_MILLIONTH

public static final BigDecimal ONE_MILLIONTH

Equal to: 0.00001 (5 decimal places)

NEGATIVE_ONE

public static final BigDecimal NEGATIVE_ONE

Equal to: -1

GROUPING_CHAR_COMMA

public static final char GROUPING_CHAR_COMMA

The character ',' (comma). Used here to specify that commas should be used for any necessary thousand's grouping (for example: 12,345). There is nothing special about this char; it is simply defined as a constant for readability.

See Also:

Constant Field Values

GROUPING_CHAR_NONE

public static final char GROUPING_CHAR_NONE

Used to indicate that "thousands" should not be separated by any character at all (no grouping). The value of this char is ''.

See Also:

Constant Field Values

PAD_CHAR_SPACE

public static final char PAD_CHAR_SPACE

The character ' ' (space). Used here to specify that spaces should be used for any necessary padding. There is nothing special about this char; it is simply defined as a constant for readability.

See Also:

Constant Field Values

PAD_CHAR_ZERO

public static final char PAD_CHAR_ZERO

The character '0' (zero). Used here to specify that zeros should be used for any necessary padding. There is nothing special about this char; it is simply defined as a constant for readability.

See Also:

Constant Field Values

PAD_CHAR_NONE

public static final char PAD_CHAR_NONE

Used to indicate that there should not be any any padding done at all. The value of this char is ''.

See Also:

Constant Field Values

ZERO_LEN_ARRAY

public static final BigDecimal[] ZERO_LEN_ARRAY

An array of BigDecimal with a length of zero.

Method Detail

isSame

public static boolean isSame(BigDecimal a,
                             BigDecimal b)

Compares two BigDecimals to see if they are the "same" (without regard to the scales of each one). Scale is not considered, for example 2.0 and 2.00 are consider to be the same (see compareTo on BigDecimal). Returns true if a is the same as b. Specifically, they are the same if either of the following are true:

• ( a == null ) && ( b == null )
• ( a != null ) && ( b != null ) && ( a.compareTo(b) == 0 )

Parameters:

a - the first number or null

b - the second number or null

Returns:

true if the numbers numerically the same, or if both parameters are null.

isDifferent

public static boolean isDifferent(BigDecimal a,
                                  BigDecimal b)

Compares two BigDecimals to see if they are "different" (without regard to the scales of each one). Scale is not considered, for example 2.0 and 2.00 are consider to be the same (see compareTo on BigDecimal). Returns true if a is different than b. Specifically, they are different if any of the following are true:

• ( a == null ) && ( b != null )
• ( a != null ) && ( b == null )
• ( a != null ) && ( b != null ) && ( a.compareTo(b) != 0 )

Parameters:

a - the first number or null

b - the second number or null

Returns:

true if the numbers differ by more than just scale, or if only one of them is null.

equalTo

public static boolean equalTo(BigDecimal a,
                              BigDecimal b)
                       throws IllegalArgumentException

Returns true if a is numerically equal to b (with no regard to scale).

Throws:

IllegalArgumentException - if either a or b is null.

notEqualTo

public static boolean notEqualTo(BigDecimal a,
                                 BigDecimal b)
                          throws IllegalArgumentException

Returns true if a is numerically not equal to b (with no regard to scale).

Throws:

IllegalArgumentException - if either a or b is null.

lessThan

public static boolean lessThan(BigDecimal a,
                               BigDecimal b)
                        throws IllegalArgumentException

Returns true if a is numerically less than b (with no regard to scale).

Throws:

IllegalArgumentException - if either a or b is null.

lessThanOrEqualTo

public static boolean lessThanOrEqualTo(BigDecimal a,
                                        BigDecimal b)
                                 throws IllegalArgumentException

Returns true if a is numerically less than or equal to b (with no regard to scale).

Throws:

IllegalArgumentException - if either a or b is null.

greaterThan

public static boolean greaterThan(BigDecimal a,
                                  BigDecimal b)
                           throws IllegalArgumentException

Returns true if a is numerically greater than b (with no regard to scale).

Throws:

IllegalArgumentException - if either a or b is null.

greaterThanOrEqualTo

public static boolean greaterThanOrEqualTo(BigDecimal a,
                                           BigDecimal b)
                                    throws IllegalArgumentException

Returns true if a is numerically greater than or equal to b (with no regard to scale).

Throws:

IllegalArgumentException - if either a or b is null.

notLessThan

public static boolean notLessThan(BigDecimal a,
                                  BigDecimal b)
                           throws IllegalArgumentException

Returns true if a is numerically not less than b (with no regard to scale). This is the same as saying: returns true if a is numerically greater than or equal to b.

Throws:

IllegalArgumentException - if either a or b is null.

notGreaterThan

public static boolean notGreaterThan(BigDecimal a,
                                     BigDecimal b)
                              throws IllegalArgumentException

Returns true if a is numerically not greater than b (with no regard to scale). This is the same as saying: returns true if a is numerically less than or equal to b.

Throws:

IllegalArgumentException - if either a or b is null.

max

public static BigDecimal max(BigDecimal a,
                             BigDecimal b)
                      throws IllegalArgumentException

Returns the numerically larger of a and b (with no regard to scale). If they are numerically equal, then a is returned.

Throws:

IllegalArgumentException - if either a or b is null.

max

public static BigDecimal max(BigDecimal a,
                             BigDecimal b,
                             BigDecimal c)
                      throws IllegalArgumentException

Returns the numerically largest of a, b and c (with no regard to scale). If they are numerically equal, then a is returned.

Throws:

IllegalArgumentException - if either a, b, or c is null.

min

public static BigDecimal min(BigDecimal a,
                             BigDecimal b)
                      throws IllegalArgumentException

Returns the numerically smaller of a and b (with no regard to scale). If they are numerically equal, then a is returned.

Throws:

IllegalArgumentException - if either a or b is null.

min

public static BigDecimal min(BigDecimal a,
                             BigDecimal b,
                             BigDecimal c)
                      throws IllegalArgumentException

Returns the numerically smallest of a, b and c (with no regard to scale). If they are numerically equal, then a is returned.

Throws:

IllegalArgumentException - if either a, b, or c is null.

rangeBound

public static BigDecimal rangeBound(BigDecimal minValue,
                                    BigDecimal value,
                                    BigDecimal maxValue)
                             throws IllegalArgumentException

Bounds value to the specified range. If value is less than minValue then minValue is returned. If value is greater than maxValue then maxValue is returned. Scale is not considered.

Throws:

IllegalArgumentException - if any of minValue, value, or maxValue is null.

isZero

public static boolean isZero(BigDecimal val)
                      throws IllegalArgumentException

Returns true if val is numerically equal to ZERO (with no regard to scale).

Throws:

IllegalArgumentException - if val is null.

isNotZero

public static boolean isNotZero(BigDecimal val)
                         throws IllegalArgumentException

Returns true if val is numerically not equal to ZERO (with no regard to scale).

Throws:

IllegalArgumentException - if val is null.

isNegative

public static boolean isNegative(BigDecimal val)
                          throws IllegalArgumentException

Returns true if val is negative (numerically less than ZERO).

Throws:

IllegalArgumentException - if val is null.

isNotNegative

public static boolean isNotNegative(BigDecimal val)
                             throws IllegalArgumentException

Returns true if val is non-negative (numerically greater than or equal to ZERO).

Throws:

IllegalArgumentException - if val is null.

isPositive

public static boolean isPositive(BigDecimal val)
                          throws IllegalArgumentException

Returns true if val is positive (numerically greater than ZERO). Note that zero is not considered to be a positive number.

Throws:

IllegalArgumentException - if val is null.

isNotPositive

public static boolean isNotPositive(BigDecimal val)
                             throws IllegalArgumentException

Returns true if val is non-positive (numerically less than or equal to ZERO). Note that zero is not considered to be a positive number.

Throws:

IllegalArgumentException - if val is null.

isEmpty

public static boolean isEmpty(BigDecimal val)

Returns true if the specified BigDecimal is either null or zero.

isNotEmpty

public static boolean isNotEmpty(BigDecimal val)

Returns true if the specified BigDecimal is not null and is not equal to zero.

toArray

public static BigDecimal[] toArray(Collection<BigDecimal> bigDecimals)

parseValue

public static Value parseValue(String source)

Permissively parses the passed String into a Value that if not empty, wraps an instance of BigDecimal. Parses the passed string by ignoring all characters not in the set {0, 1, 2 ,3 ,4 ,5 ,6 ,7 ,8 ,9 ,. , -}. The negative sign '-' is ignored if it is not the first valid character; and only the first decimal point '.' is kept, any additional decimal points are ignored. There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming).

Calling the getBigDecimal() method on the returned Value is inexpensive (the reference to the wrapped BigDecimal created during parsing is simply returned—no new object is created and no parsing need be done).

If null is passed in, then ValueFactory.NULL_INSTANCE is returned. NULL_INSTANCE always returns true for isEmpty() and for isNull(); and returns false for isNumeric().

If a zero-length String, a String containing only whitespace, or a String that contains no valid characters is passed in, then ValueFactory.ZERO_LEN_STRING_INSTANCE is returned. ZERO_LEN_STRING_INSTANCE always returns true for isEmpty(); and returns false for isNull() and for isNumeric().

Parameters:

source - to be parsed

Returns:

the resulting Value.

See Also:

parseBigDecimal(String), StringTools.winnowDecimal(String)

parseBigDecimal

public static BigDecimal parseBigDecimal(String source)
                                  throws ValueException

Permissively parses the passed String into a BigDecimal. Parses the passed string by ignoring all characters not in the set {0, 1, 2 ,3 ,4 ,5 ,6 ,7 ,8 ,9 ,. , -}. The negative sign '-' is ignored if it is not the first valid character; and only the first decimal point '.' is kept, any additional decimal points are ignored. There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming).

If null, a zero-length String, a String containing only whitespace, or a String that contains no valid characters is passed in, then a ValueException is thrown.

Parameters:

source - to be parsed

Returns:

the resulting BigDecimal.

Throws:

ValueException - if the parsing fails. ValueException is a RuntimeException and is not required to be caught.

See Also:

parseBigDecimal(String, BigDecimal), parseValue(String), StringTools.winnowDecimal(String)

parseBigDecimal

public static BigDecimal parseBigDecimal(String source,
                                         BigDecimal defaultValue)

Permissively parses the passed String into a BigDecimal. Parses the passed string by ignoring all characters not in the set {0, 1, 2 ,3 ,4 ,5 ,6 ,7 ,8 ,9 ,. , -}. The negative sign '-' is ignored if it is not the first valid character; and only the first decimal point '.' is kept, any additional decimal points are ignored. There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming).

If null, a zero-length String, a String containing only whitespace, or a String that contains no valid characters is passed in, then the specified defaultValue is returned.

Parameters:

source - to be parsed

defaultValue - the value to return if parsing does not find any valid characters.

Returns:

the resulting BigDecimal, or the specified defaultValue.

See Also:

parseBigDecimal(String), StringTools.winnowDecimal(String)

parseDouble

public static double parseDouble(String source)
                          throws ValueException

Permissively parses the passed String into a double. Parses the passed string by ignoring all characters not in the set {0, 1, 2 ,3 ,4 ,5 ,6 ,7 ,8 ,9 ,. , -}. The negative sign '-' is ignored if it is not the first valid character; and only the first decimal point '.' is kept, any additional decimal points are ignored. There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming).

If null, a zero-length String, a String containing only whitespace, or a String that contains no valid characters is passed in, then a ValueException is thrown.

Parameters:

source - to be parsed

Returns:

the resulting double.

Throws:

ValueException - if the parsing fails. ValueException is a RuntimeException and is not required to be caught.

See Also:

parseDouble(String, double), parseValue(String), StringTools.winnowDecimal(String)

parseDouble

public static double parseDouble(String source,
                                 double defaultValue)

Permissively parses the passed String into a double. Parses the passed string by ignoring all characters not in the set {0, 1, 2 ,3 ,4 ,5 ,6 ,7 ,8 ,9 ,. , -}. The negative sign '-' is ignored if it is not the first valid character; and only the first decimal point '.' is kept, any additional decimal points are ignored. There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming).

If null, a zero-length String, a String containing only whitespace, or a String that contains no valid characters is passed in, then the specified defaultValue is returned.

Parameters:

source - to be parsed

defaultValue - the value to return if parsing does not find any valid characters.

Returns:

the resulting double, or the specified defaultValue.

See Also:

parseDouble(String), StringTools.winnowDecimal(String)

convert

public static BigDecimal convert(int value)

Converts the specified value to a BigDecimal returning one of the shared, common, immutable instances if possible.

convert

public static BigDecimal convert(long value)

Converts the specified value to a BigDecimal returning one of the shared, common, immutable instances if possible.

convert

public static BigDecimal convert(Number value)

Converts the specified value to a BigDecimal returning one of the shared, common, immutable instances if possible.

round

public static BigDecimal round(BigDecimal value,
                               BigDecimal nearest,
                               int roundingMode)

Returns value rounded to the nearest multiple of the specified value nearest. Result has a scale of nearest.scale(). If necessary, the specified roundingMode is used (the valid rounding modes are defined in BigDecimal).

round

public static BigDecimal round(BigDecimal value,
                               BigDecimal nearest)

Equivalent to: round(value, nearest, BigDecimal.ROUND_HALF_UP)

round

public static BigDecimal round(BigDecimal value)

Rounds to the nearest 1 (nearest integer). Result has a scale of 0. If value already has a scale of 0, then value is simply (and efficiently) returned. If necessary, BigDecimal.ROUND_HALF_UP is used.

roundTenth

public static BigDecimal roundTenth(BigDecimal value)

Rounds to the nearest 0.1. Result has a scale of 1. If value already has a scale of 1, then value is simply (and efficiently) returned. If necessary, BigDecimal.ROUND_HALF_UP is used.

roundHundredth

public static BigDecimal roundHundredth(BigDecimal value)

Rounds to the nearest 0.01. Result has a scale of 2. If value already has a scale of 2, then value is simply (and efficiently) returned. If necessary, BigDecimal.ROUND_HALF_UP is used.

roundThousandth

public static BigDecimal roundThousandth(BigDecimal value)

Rounds to the nearest 0.001. Result has a scale of 3. If value already has a scale of 3, then value is simply (and efficiently) returned. If necessary, BigDecimal.ROUND_HALF_UP is used.

roundSixteenth

public static BigDecimal roundSixteenth(BigDecimal value)

Rounds to the nearest 1/16 (multiple of 0.0625). Result has a scale of 4. If necessary, BigDecimal.ROUND_HALF_UP is used.

roundEighth

public static BigDecimal roundEighth(BigDecimal value)

Rounds to the nearest 1/8 (multiple of 0.125). Result has a scale of 3. If necessary, BigDecimal.ROUND_HALF_UP is used.

roundQuarter

public static BigDecimal roundQuarter(BigDecimal value)

Rounds to the nearest 1/4 (multiple of 0.25). Result has a scale of 2. If necessary, BigDecimal.ROUND_HALF_UP is used.

roundHalf

public static BigDecimal roundHalf(BigDecimal value)

Rounds to the nearest 1/2 (multiple of 0.5). Result has a scale of 1. If necessary, BigDecimal.ROUND_HALF_UP is used.

roundPenny

public static BigDecimal roundPenny(BigDecimal value)

Same as roundHundredth(BigDecimal). This method exists to enhance readability when US currency is being used.

roundDollar

public static BigDecimal roundDollar(BigDecimal value)

Same as round(BigDecimal) (nearest integer). This method exists to enhance readability when US currency is being used.

sum

public static BigDecimal sum(BigDecimal[] val)

Returns the sum of all of the values in the array passed in. If any slot in the array is null, then that slot is ignored (skipped).

Parameters:

val - values to total up.

Returns:

the sum of all the values. Zero is returned if val is empty (null or zero-length).

See Also:

NumberTools.sum(int[]), NumberTools.sum(double[])

getMaxValueFor

public static BigDecimal getMaxValueFor(int integerDigitCount,
                                        int fractionalDigitCount)

Returns the largest positive value than can fit into the specified number of integer and fractional digits (all nines).

Parameters:

integerDigitCount - the number of digits to the left of the decimal decimal point.

fractionalDigitCount - the number of digits to the right of the decimal point.

Returns:

the largest positive value

getMinValueFor

public static BigDecimal getMinValueFor(int integerDigitCount,
                                        int fractionalDigitCount)

Returns the most negative value than can fit into the specified number of integer and fractional digits (all nines preceded by a minus sign).

Parameters:

integerDigitCount - the number of digits to the left of the decimal decimal point.

fractionalDigitCount - the number of digits to the right of the decimal point.

Returns:

the most negative value

format

public static String format(BigDecimal value,
                            int integerDigitCount,
                            char integerPaddingChar,
                            int fractionalDigitCount,
                            char fractionalPaddingChar,
                            char thousandGroupingChar)

format

public static String format(BigDecimal value,
                            int integerDigitCount,
                            int fractionalDigitCount)