de.ipcon.tools

Class BigDecimalTools

java.lang.Object

de.ipcon.tools.BigDecimalTools

public final class BigDecimalTools
extends java.lang.Object

Provides static tool methods for BigDecimal and related objects.

Field Summary

Fields

Modifier and Type	Field and Description
static org.apache.log4j.Logger	log

Constructor Summary

Constructors

Constructor and Description
BigDecimalTools()

Method Summary

Modifier and Type	Method and Description
static java.math.BigDecimal	chapterStringToBigDecimal(java.lang.String chapterString, int maxDigitsPerSegment) Converts a chapter string (e.g., "1.2", "1,23", "3.5.1") to a BigDecimal, maintaining the intended order by padding each chapter segment with leading zeros.
static boolean	equalsByCompare(java.math.BigDecimal[] a, java.math.BigDecimal[] b) Returns true if the two specified arrays of BigDecimals are equal to one another.
static int	getOrderOfMagnitude(java.math.BigDecimal bd) Returns the order of magnitude, i.e., the nearest power of ten, for the given BigDecimal.
static boolean	isWithinTolerance(java.math.BigDecimal number, java.math.BigDecimal centralValue, java.math.BigDecimal tolerance) Checks whether a given BigDecimal is within a specified tolerance or margin of error from a central value.
static boolean	liesInInterval(java.math.BigDecimal n, java.math.BigDecimal lowerBound, java.math.BigDecimal upperBound) Returns true if n is in the closed interval [lowerBound, upperBound].
static boolean	liesInInterval(java.math.BigDecimal n, java.math.BigDecimal lowerBound, java.math.BigDecimal upperBound, boolean excludingLeft) Returns true if n is in the closed interval [lowerBound, upperBound].
static boolean	liesInInterval(java.math.BigDecimal n, java.math.BigDecimal lowerBound, java.math.BigDecimal upperBound, boolean excludingLeft, boolean excludingRight) Returns true if n is in the closed interval [lowerBound, upperBound].
static boolean	liesInLeftOpenInterval(java.math.BigDecimal n, java.math.BigDecimal lowerBound, java.math.BigDecimal upperBound) Returns true if n is in the left open interval (lowerBound, upperBound].
static boolean	liesInOpenInterval(java.math.BigDecimal n, java.math.BigDecimal lowerBound, java.math.BigDecimal upperBound) Returns true if n is in the open interval (lowerBound, upperBound).
static boolean	liesInRightOpenInterval(java.math.BigDecimal n, java.math.BigDecimal lowerBound, java.math.BigDecimal upperBound) Returns true if n is in the right open interval [lowerBound, upperBound).
static java.math.BigDecimal	normalize(java.math.BigDecimal val) Normalizes a given BigDecimal by removing trailing zeros while preserving its original scale.
static java.math.BigDecimal	normalize(java.math.BigDecimal val, int maxScale) Normalizes a given BigDecimal by capping its scale and removing trailing zeros.
static java.math.BigDecimal	roundToNearestOrderOfMagnitude(java.math.BigDecimal bd) Rounds the passed BigDecimal to the nearest order of magnitude, i.e., power of ten.
static java.math.BigDecimal	roundToNextOrderOfMagnitude(java.math.BigDecimal bd) Rounds the passed BigDecimal to the next order of magnitude, i.e., power of ten.
static java.math.BigDecimal	roundUpToGivenFraction(java.math.BigDecimal val, java.math.BigDecimal ceiling) Rounds the provided value val to the specified ceiling.
static java.math.BigDecimal	sqrt(java.math.BigDecimal value) Calculates an approximation of the square root for the passed BigDecimal to a precision of around 30 total digits.
static java.math.BigDecimal	sum(java.math.BigDecimal[] array)
static java.math.BigDecimal	sum(java.lang.Iterable<java.math.BigDecimal> iter)
static java.math.BigDecimal	toBigDecimal(java.lang.Number number) Creates a BigDecimal from a Number.

Methods inherited from class java.lang.Object

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

Field Detail

log

public static final org.apache.log4j.Logger log

Constructor Detail

BigDecimalTools

public BigDecimalTools()

Method Detail

toBigDecimal

public static final java.math.BigDecimal toBigDecimal(java.lang.Number number)

Creates a BigDecimal from a Number.

Parameters:

number - the Number to generate the BigDecimal from

Returns:

a BigDecimal with the value of Number

equalsByCompare

public static final boolean equalsByCompare(java.math.BigDecimal[] a,
                                            java.math.BigDecimal[] b)

Returns true if the two specified arrays of BigDecimals are equal to one another. The two arrays are considered equal if both arrays contain the same number of elements, and all corresponding pairs of elements in the two arrays have the same value. Two objects e1 and e2 are considered equal if (e1==null ? e2==null : e1.compareTo(e2) == 0). In other words, the two arrays are equal if they contain the same values in the same order. Also, two array references are considered equal if both are null. Similar to Arrays.equals(Object[], Object[]), only that it uses BigDecimal.compareTo(java.math.BigDecimal) for the equality check.

Parameters:

a - one array tested for compare equality, nullable.

b - the other array tested for compare equality, nullable.

Returns:

true if both arrays contain the same values.

sum

public static final java.math.BigDecimal sum(java.math.BigDecimal[] array)

Returns:

a sum of all BigDecimals in the given array as a BigDecimal

sum

public static final java.math.BigDecimal sum(java.lang.Iterable<java.math.BigDecimal> iter)

Returns:

a sum of all BigDecimals in the given Iterable as a BigDecimal

isWithinTolerance

public static final boolean isWithinTolerance(java.math.BigDecimal number,
                                              java.math.BigDecimal centralValue,
                                              java.math.BigDecimal tolerance)

Checks whether a given BigDecimal is within a specified tolerance or margin of error from a central value.

Parameters:

number - the BigDecimal to check.

centralValue - the central value to use as a reference point.

tolerance - the tolerance value that determines the allowed deviation from the central value.

Returns:

true if the BigDecimal is within the tolerance, false otherwise.

Throws:

java.lang.IllegalArgumentException - if the number, centralValue, or tolerance parameters are null or the tolerance parameter is negative.

liesInInterval

public static final boolean liesInInterval(java.math.BigDecimal n,
                                           java.math.BigDecimal lowerBound,
                                           java.math.BigDecimal upperBound)

Returns true if n is in the closed interval [lowerBound, upperBound]. Null values for lowerBound or upperBound represent infinity.

Parameters:

n - the BigDecimal to check

lowerBound - the lower bound of the interval

upperBound - the upper bound of the interval

Returns:

true if n is in the specified interval

Throws:

java.lang.IllegalArgumentException - if the input is invalid

liesInInterval

public static final boolean liesInInterval(java.math.BigDecimal n,
                                           java.math.BigDecimal lowerBound,
                                           java.math.BigDecimal upperBound,
                                           boolean excludingLeft)

Returns true if n is in the closed interval [lowerBound, upperBound]. Null values for lowerBound or upperBound represent infinity.

Parameters:

n - the BigDecimal to check

lowerBound - the lower bound of the interval

upperBound - the upper bound of the interval

excludingLeft - whether to exclude the left endpoint

Returns:

true if n is in the specified interval

Throws:

java.lang.IllegalArgumentException - if the input is invalid

liesInInterval

public static final boolean liesInInterval(java.math.BigDecimal n,
                                           java.math.BigDecimal lowerBound,
                                           java.math.BigDecimal upperBound,
                                           boolean excludingLeft,
                                           boolean excludingRight)

Returns true if n is in the closed interval [lowerBound, upperBound]. Null values for lowerBound or upperBound represent infinity.

Parameters:

n - the BigDecimal to check

lowerBound - the lower bound of the interval

upperBound - the upper bound of the interval

excludingLeft - whether to exclude the left endpoint

excludingRight - whether to exclude the right endpoint

Returns:

true if n is in the specified interval

Throws:

java.lang.IllegalArgumentException - if the input is invalid

liesInOpenInterval

public static final boolean liesInOpenInterval(java.math.BigDecimal n,
                                               java.math.BigDecimal lowerBound,
                                               java.math.BigDecimal upperBound)

Returns true if n is in the open interval (lowerBound, upperBound). Null values for lowerBound or upperBound represent infinity.

Parameters:

n - the BigDecimal to check

lowerBound - the lower bound of the interval

upperBound - the upper bound of the interval

Returns:

true if n is in the specified open interval

liesInLeftOpenInterval

public static final boolean liesInLeftOpenInterval(java.math.BigDecimal n,
                                                   java.math.BigDecimal lowerBound,
                                                   java.math.BigDecimal upperBound)

Returns true if n is in the left open interval (lowerBound, upperBound]. Null values for lowerBound or upperBound represent infinity.

Parameters:

n - the BigDecimal to check

lowerBound - the lower bound of the interval

upperBound - the upper bound of the interval

Returns:

true if n is in the specified left open interval

liesInRightOpenInterval

public static final boolean liesInRightOpenInterval(java.math.BigDecimal n,
                                                    java.math.BigDecimal lowerBound,
                                                    java.math.BigDecimal upperBound)

Returns true if n is in the right open interval [lowerBound, upperBound). Null values for lowerBound or upperBound represent infinity.

Parameters:

n - the BigDecimal to check

lowerBound - the lower bound of the interval

upperBound - the upper bound of the interval

Returns:

true if n is in the specified right open interval

sqrt

public static final java.math.BigDecimal sqrt(java.math.BigDecimal value)

Calculates an approximation of the square root for the passed BigDecimal to a precision of around 30 total digits. For Java < 9, we are using the Babylonian method for approximating the square root. It will fail for large values that cannot be represented by a double anymore. For Java >= 9, the BigDecimal#sqrt(MathContext) function is called with MathContext.DECIMAL128, which guarantees a precision of 34 digits with HALF_EVEN rounding, but we cap that at 30 total digits for consistency.

Parameters:

value - the BigDecimal for which to calculate the square root

Returns:

the square root approximation

roundUpToGivenFraction

public static final java.math.BigDecimal roundUpToGivenFraction(java.math.BigDecimal val,
                                                                java.math.BigDecimal ceiling)

Rounds the provided value val to the specified ceiling.

Parameters:

val - the value to round up

ceiling - the ceiling to round up to

Returns:

the rounded value

Throws:

java.lang.IllegalStateException - if the input value is negative

getOrderOfMagnitude

public static final int getOrderOfMagnitude(java.math.BigDecimal bd)

Returns the order of magnitude, i.e., the nearest power of ten, for the given BigDecimal. E.g., 526 will return 3, as 1000 is the nearest power of 10 and is 10^3. 2456 will also return 3, as 1000 is again the nearest power of 10.

Parameters:

bd - the BigDecimal for which to determine the order of magnitude

Returns:

the order of magnitude

Throws:

java.lang.IllegalArgumentException - if the input is negative

roundToNearestOrderOfMagnitude

public static final java.math.BigDecimal roundToNearestOrderOfMagnitude(java.math.BigDecimal bd)

Rounds the passed BigDecimal to the nearest order of magnitude, i.e., power of ten. E.g., 526 will return 1000, as 1000 is the nearest power of 10. 2456 will also return 1000, as 1000 is again the nearest power of 10.

Parameters:

bd - the BigDecimal to round

Returns:

the rounded BigDecimal

roundToNextOrderOfMagnitude

public static final java.math.BigDecimal roundToNextOrderOfMagnitude(java.math.BigDecimal bd)

Rounds the passed BigDecimal to the next order of magnitude, i.e., power of ten. E.g., 526 will return 1000, as 1000 is the next power of 10. 2456 will return 10000, as 10000 is the next power of 10.

Parameters:

bd - the BigDecimal to round

Returns:

the rounded BigDecimal

normalize

public static final java.math.BigDecimal normalize(java.math.BigDecimal val)

Normalizes a given BigDecimal by removing trailing zeros while preserving its original scale.

This method is a convenience variant of normalize(BigDecimal, int) that retains the original scale of the provided BigDecimal.

Operations performed:

1. Removes any trailing zeros from the provided BigDecimal to ensure a cleaner representation.

Important Considerations:

• Unexpected Exponent Notation: When converting the result to a String, especially when working with very large or very small numbers, you may encounter scientific notation (e.g., 1E+10). To avoid this, use toPlainString() on the BigDecimal for a more predictable representation.
• Localized String Representation: For UI displays, reports, and other customer-facing frontends, it is recommended to use L10n#formatDecimal(BigDecimal, String, Locale) to get a properly formatted string representation according to a given pattern and locale.
• Null Handling: If the input val is null, the method returns null.

Example Usage:

 BigDecimal value = new BigDecimal("123.45000");
 BigDecimal normalizedValue = normalize(value);
 System.out.println(normalizedValue); // Output: "123.45"

 BigDecimal largeValue = new BigDecimal("12345000000");
 BigDecimal normalizedLargeValue = normalize(largeValue);
 System.out.println(normalizedLargeValue.toString()); // Output: "1.2345E+10"
 System.out.println(normalizedLargeValue.toPlainString()); // Output: "12345000000"
 

Parameters:

val - the BigDecimal to normalize

Returns:

the normalized BigDecimal without trailing zeros, retaining the original scale, or null if val is null

See Also:

normalize(BigDecimal, int)

normalize

public static final java.math.BigDecimal normalize(java.math.BigDecimal val,
                                                   int maxScale)

Normalizes a given BigDecimal by capping its scale and removing trailing zeros.

This method performs two main operations on the provided BigDecimal:

1. If the current scale of the BigDecimal exceeds the specified maxScale, it rounds the value to the maxScale using BigDecimal.ROUND_HALF_UP rounding mode.
2. Removes any trailing zeros from the resultant BigDecimal to ensure a cleaner and normalized representation.

Important Considerations:

• Rounding Mode: The method uses BigDecimal.ROUND_HALF_UP for rounding when reducing the scale. This is a standard rounding mode where values are rounded to the nearest neighbor, and ties are broken by rounding up.
• Unexpected Exponent Notation: When converting the result to a String, especially when working with very large or very small numbers, you may encounter scientific notation (e.g., 1E+10). To avoid this, use toPlainString() on the BigDecimal for a more predictable representation.
• Localized String Representation: For UI displays, reports, and other customer-facing frontends, it is recommended to use L10n#formatDecimal(BigDecimal, String, Locale) to get a properly formatted string representation according to a given pattern and locale.
• Null Handling: If the input val is null, the method returns null.
• Preserving Scale: Passing -1 as maxScale will retain the original scale of the passed BigDecimal.

Example Usage:

 BigDecimal value = new BigDecimal("123.54321");
 BigDecimal normalizedValue = normalize(value, 2);
 System.out.println(normalizedValue); // Output: "123.54"

 BigDecimal largeValue = new BigDecimal("12345000000");
 BigDecimal normalizedLargeValue = normalize(largeValue, -1);
 System.out.println(normalizedLargeValue.toString()); // Output: "1.2345E+10"
 System.out.println(normalizedLargeValue.toPlainString()); // Output: "12345000000"
 

Parameters:

val - the BigDecimal to normalize

maxScale - the maximum scale to set, use -1 to retain the original scale

Returns:

the normalized BigDecimal, capped to the specified scale and without trailing zeros, or null if val is null

chapterStringToBigDecimal

public static java.math.BigDecimal chapterStringToBigDecimal(java.lang.String chapterString,
                                                             int maxDigitsPerSegment)

Converts a chapter string (e.g., "1.2", "1,23", "3.5.1") to a BigDecimal, maintaining the intended order by padding each chapter segment with leading zeros. Allows configuration of the maximum number of digits per chapter segment.

Parameters:

chapterString - The string representing the chapter number. Supports both dots (".") and commas (",") as separators.

maxDigitsPerSegment - The maximum number of digits to consider for each chapter segment when padding with leading zeros. This ensures correct lexicographical ordering when the resulting BigDecimal values are compared.

Returns:

A BigDecimal representation of the chapter string, where each segment is padded with leading zeros to the specified maxDigitsPerSegment length and placed after the decimal point (e.g., "1.2" with maxDigitsPerSegment of 3 becomes 0.001002). Returns BigDecimal.ZERO if the input chapterString is null or empty. Non-numeric parts in the chapter string will be treated leniently as 0.

Throws:

java.lang.IllegalArgumentException - If any chapter segment (after trimming) has more digits than maxDigitsPerSegment.