BigDecimal (Groovy JDK enhancements)

Package: java.math

## Class BigDecimal

- - ### Methods Summary

    Methods
    Return type | Name and parameters
    --- | ---
    `void` | `downto(Number to, Closure closure)` Iterates from this number down to the given number, inclusive, decrementing by one each time.
    `Boolean` | `isAtLeast(String right)` Compare a BigDecimal to a String representing a number.
    `Boolean` | `isAtLeast(BigDecimal right)` Compare a BigDecimal to another.
    `Number` | `multiply(Double right)` Multiply a BigDecimal and a Double.
    `Number` | `multiply(BigInteger right)` Multiply a BigDecimal and a BigInteger.
    `Number` | `power(Integer exponent)` Power of a BigDecimal to an integer certain exponent.
    `BigDecimal` | `round()` Round the value Note that this method differs from BigDecimal#round(java.math.MathContext) which specifies the digits to retain starting from the leftmost nonzero digit.
    `BigDecimal` | `round(int precision)` Round the value Note that this method differs from BigDecimal#round(java.math.MathContext) which specifies the digits to retain starting from the leftmost nonzero digit.
    `BigDecimal` | `trunc()` Truncate the value
    `BigDecimal` | `trunc(int precision)` Truncate the value
    `void` | `upto(Number to, Closure closure)` Iterates from this number up to the given number, inclusive, incrementing by one each time.

  - #### Methods inherited from class java.lang.Number

    `abs`, `and`, `asBoolean`, `asType`, `bitwiseNegate`, `compareTo`, `compareTo`, `div`, `div`, `downto`, `intdiv`, `intdiv`, `isCase`, `isNotCase`, `leftShift`, `minus`, `minus`, `mod`, `multiply`, `multiply`, `next`, `or`, `plus`, `plus`, `plus`, `power`, `previous`, `rightShift`, `rightShiftUnsigned`, `step`, `times`, `toBigDecimal`, `toBigInteger`, `toDouble`, `toFloat`, `toInteger`, `toLong`, `unaryMinus`, `unaryPlus`, `upto`, `xor`

  - #### Methods inherited from class java.lang.Object

    `addShutdownHook`, `any`, `any`, `asBoolean`, `asType`, `collect`, `collect`, `collect`, `dump`, `each`, `eachMatch`, `eachMatch`, `eachWithIndex`, `every`, `every`, `find`, `find`, `findAll`, `findAll`, `findIndexOf`, `findIndexOf`, `findIndexValues`, `findIndexValues`, `findLastIndexOf`, `findLastIndexOf`, `findResult`, `findResult`, `findResult`, `findResult`, `getAt`, `getMetaClass`, `getMetaPropertyValues`, `getProperties`, `grep`, `grep`, `hasProperty`, `identity`, `inject`, `inject`, `inspect`, `invokeMethod`, `is`, `isCase`, `isNotCase`, `iterator`, `metaClass`, `print`, `print`, `printf`, `printf`, `println`, `println`, `println`, `putAt`, `respondsTo`, `respondsTo`, `setMetaClass`, `split`, `sprintf`, `sprintf`, `stream`, `tap`, `toString`, `use`, `use`, `use`, `with`, `with`, `withCloseable`, `withStream`, `withTraits`

  - #### Methods inherited from interface java.lang.Comparable

    `numberAwareCompareTo`

- - ### Methods Detail

    - #### public void downto(Number to, Closure closure)

      Iterates from this number down to the given number, inclusive, decrementing by one each time. Each number is passed to the closure. Example:

          10.5.downto(0) {
            println it
          }

      Prints numbers 10.5, 9.5 ... to 0.5.
      Parameters:
        `to` - the end number
        `closure` - the code to execute for each number
      Since:
        1.0

    - #### public Boolean isAtLeast(String right)

      Compare a BigDecimal to a String representing a number. A fluent api style alias for `compareTo`.

      Parameters:
        `right` - a String representing a number
      Returns:
        true if left is equal to or bigger than the value represented by right
      Since:
        3.0.1

    - #### public Boolean isAtLeast(BigDecimal right)

      Compare a BigDecimal to another. A fluent api style alias for `compareTo`.

      Parameters:
        `right` - a BigDecimal
      Returns:
        true if left is equal to or bigger than right
      Since:
        3.0.1

    - #### public Number multiply(Double right)

      Multiply a BigDecimal and a Double. Note: This method was added to enforce the Groovy rule of BigDecimal*Double == Double. Without this method, the multiply(BigDecimal) method in BigDecimal would respond and return a BigDecimal instead. Since BigDecimal is preferred over Number, the Number*Number method is not chosen as in older versions of Groovy.

      Parameters:
        `right` - a Double
      Returns:
        the multiplication of left by right
      Since:
        1.0

    - #### public Number multiply(BigInteger right)

      Multiply a BigDecimal and a BigInteger. Note: This method was added to enforce the Groovy rule of BigDecimal*long == long. Without this method, the multiply(BigDecimal) method in BigDecimal would respond and return a BigDecimal instead. Since BigDecimal is preferred over Number, the Number*Number method is not chosen as in older versions of Groovy. BigInteger is the fallback for all integer types in Groovy

      Parameters:
        `right` - a BigInteger
      Returns:
        the multiplication of left by right
      Since:
        1.0

    - #### public Number power(Integer exponent)

      Power of a BigDecimal to an integer certain exponent. If the exponent is positive, call the BigDecimal.pow(int) method to maintain precision. Called by the '**' operator.

      Parameters:
        `exponent` - an Integer exponent
      Returns:
        a Number to the power of the exponent

    - #### public BigDecimal round()

      Round the value

      Note that this method differs from BigDecimal#round(java.math.MathContext) which specifies the digits to retain starting from the leftmost nonzero digit. This method rounds the integral part to the nearest whole number.

      Returns:
        the rounded value of that BigDecimal
      Since:
        2.5.0
      See Also:
        BigDecimal#round(int)
        BigDecimal#round(java.math.MathContext)

    - #### public BigDecimal round(int precision)

      Round the value

      Note that this method differs from BigDecimal#round(java.math.MathContext) which specifies the digits to retain starting from the leftmost nonzero digit. This method operates on the fractional part of the number and the precision argument specifies the number of digits to the right of the decimal point to retain.

      Parameters:
        `precision` - the number of decimal places to keep
      Returns:
        a BigDecimal rounded to the number of decimal places specified by precision
      Since:
        2.5.0
      See Also:
        BigDecimal#round()
        BigDecimal#round(java.math.MathContext)

    - #### public BigDecimal trunc()

      Truncate the value

      Returns:
        a BigDecimal truncated to 0 decimal places
      Since:
        2.5.0
      See Also:
        BigDecimal#trunc(int)

    - #### public BigDecimal trunc(int precision)

      Truncate the value

      Parameters:
        `precision` - the number of decimal places to keep
      Returns:
        a BigDecimal truncated to the number of decimal places specified by precision
      Since:
        2.5.0
      See Also:
        BigDecimal#trunc()

    - #### public void upto(Number to, Closure closure)

      Iterates from this number up to the given number, inclusive, incrementing by one each time.

          0.1.upto( 10 ) {
            println it
          }

      Prints numbers 0.1, 1.1, 2.1... to 9.1
      Parameters:
        `to` - the end number
        `closure` - the code to execute for each number
      Since:
        1.0