BigDecimalTools (MyTISM API Documentation)

java.lang.Object
- de.ipcon.tools.BigDecimalTools

```
public final class BigDecimalTools
extends java.lang.Object
```
Provides static tool methods for BigDecimal and related objects.

Constructor Summary

Constructors
Constructor and Description

BigDecimalTools()

Constructors
Constructor and Description
`BigDecimalTools()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`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

- 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

Class BigDecimalTools

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BigDecimalTools

Method Detail

toBigDecimal

equalsByCompare

sum

sum

isWithinTolerance

liesInInterval

liesInInterval

liesInInterval

liesInOpenInterval

liesInLeftOpenInterval

liesInRightOpenInterval

sqrt

roundUpToGivenFraction

getOrderOfMagnitude

roundToNearestOrderOfMagnitude

roundToNextOrderOfMagnitude

normalize

normalize