Package: java.lang

## [Java] Class Number

- java.lang.Number

-     public class Number
      extends Object

  GDK enhancements for Number.

  displayName:
    Number
  receiverFqcn:
    java.lang.Number

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public int` | `abs()` Gets the absolute value.
    `` | `public Number` | `and(Number right)` Bitwise AND together two Numbers.
    `` | `public boolean` | `asBoolean()` Coerce a number to a boolean value.
    `<T>` | `public T` | `asType(Class<T> type)` Transform this number to the given type, using the 'as' operator.
    `` | `public Number` | `bitwiseNegate()` Bitwise NEGATE a Number.
    `` | `public int` | `compareTo(Character right)` Compares a Number and a Character.
    `` | `public int` | `compareTo(Number right)` Compares two Numbers.
    `` | `public Number` | `div(Character right)` Divide a Number by a Character.
    `` | `public Number` | `div(Number right)` Divide two Numbers.
    `` | `public void` | `downto(Number to, Closure closure)` Iterates from this number down to the given number, inclusive, decrementing by one each time.
    `` | `public Number` | `intdiv(Character right)` Integer Divide a Number by a Character.
    `` | `public Number` | `intdiv(Number right)` Integer Divide two Numbers.
    `` | `public boolean` | `isCase(Number switchValue)` Special 'case' implementation for all numbers, which delegates to the `compareTo()` method for comparing numbers of different types.
    `` | `public boolean` | `isNotCase(Number switchValue)` Since: 4.0.0
    `` | `public Number` | `leftShift(Number operand)` Implementation of the left shift operator for integral types.
    `` | `public Number` | `minus(Character right)` Subtract a Character from a Number.
    `` | `public Number` | `minus(Number right)` Subtraction of two Numbers.
    `` | `public Number` | `mod(Number right)` Performs a division modulus operation.
    `` | `public Number` | `multiply(Character right)` Multiply a Number by a Character.
    `` | `public Number` | `multiply(Number right)`
    `` | `public Number` | `next()` Increment a Number by one.
    `` | `public Number` | `or(Number right)` Bitwise OR together two numbers.
    `` | `public Number` | `plus(Character right)` Add a Number and a Character.
    `` | `public String` | `plus(String right)` Appends a String to the string representation of this number.
    `` | `public Number` | `plus(Number right)` Add two numbers and return the result.
    `` | `public Number` | `power(Number exponent)` Power of a Number to a certain exponent.
    `` | `public Number` | `previous()` Decrement a Number by one.
    `` | `public Number` | `remainder(Number right)` Performs a division modulus operation.
    `` | `public Number` | `rightShift(Number operand)` Implementation of the right shift operator for integral types.
    `` | `public Number` | `rightShiftUnsigned(Number operand)` Implementation of the right shift (unsigned) operator for integral types.
    `` | `public void` | `step(Number to, Number stepNumber, Closure closure)` Iterates from this number up to the given number using a step increment.
    `` | `public void` | `times(Closure closure)` Executes the closure this many times, starting from zero.
    `` | `public BigDecimal` | `toBigDecimal()` Transforms a Number into a BigDecimal.
    `` | `public BigInteger` | `toBigInteger()` Transforms this Number into a BigInteger.
    `` | `public String` | `toCurrencyString()` Formats a Number as a currency String using Locale.getDefault.
    `` | `public String` | `toCurrencyString(Locale locale)` Formats a Number as a currency String using the given locale.
    `` | `public Double` | `toDouble()` Transforms a Number into a Double.
    `` | `public Float` | `toFloat()` Transforms a Number into a Float.
    `` | `public Integer` | `toInteger()` Transforms a Number into an Integer.
    `` | `public Long` | `toLong()` Transforms a Number into a Long.
    `` | `public String` | `toPercentString()` Formats a Number as a percent String using Locale.getDefault.
    `` | `public String` | `toPercentString(Locale locale)` Formats a Number as a percent String using the given locale.
    `` | `public Number` | `unaryMinus()` Negates the number.
    `` | `public Number` | `unaryPlus()` Returns the number, effectively being a noop for numbers.
    `` | `public void` | `upto(Number to, Closure closure)` Iterates from this number up to the given number, inclusive, incrementing by one each time.
    `` | `public Number` | `xor(Number right)` Bitwise XOR together two Numbers.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `addShutdownHook, any, any, asBoolean, asType, clamp, clamp, 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, inject, inject, inspect, invokeMethod, is, isCase, isNotCase, iterator, metaClass, print, print, printf, printf, println, println, println, putAt, respondsTo, respondsTo, setMetaClass, sleep, sleep, split, sprintf, sprintf, stream, takeIf, tap, toString, use, use, use, with, with, withCloseable, withCloseable, withMethodClosure, withStream, withStream, withTraits`

- - ### Method Detail

    - #### public int abs()

      Gets the absolute value.

      Note: This method is NOT called if number is a BigInteger or BigDecimal, because those classes implement a method with a better exact match.

      Returns:
        the absolute value of that Number
      Since:
        1.0

    - #### public Number and(Number right)

      Bitwise AND together two Numbers.

      Parameters:
        `right` - another Number to bitwise AND
      Returns:
        the bitwise AND of both Numbers
      Since:
        1.0

    - #### public boolean asBoolean()

      Coerce a number to a boolean value. A number is coerced to false if its double value is equal to 0, and to true otherwise.

      Returns:
        the boolean value
      Since:
        1.7.0

    - #### <T> public T asType(Class<T> type)

      Transform this number to the given type, using the 'as' operator. The following types are supported in addition to the default Object.asType:

      - BigDecimal
      - BigInteger
      - Double
      - Float
      Parameters:
        `type` - the desired type of the transformed result
      Returns:
        an instance of the given type
      Since:
        1.0

    - #### public Number bitwiseNegate()

      Bitwise NEGATE a Number.

      Returns:
        the bitwise NEGATE of the Number
      Since:
        2.2.0

    - #### public int compareTo(Character right)

      Compares a Number and a Character. The ordinal value of the Character is used in the comparison (the ordinal value is the unicode value which for simple character sets is the ASCII value).

      Parameters:
        `right` - a Character
      Returns:
        the result of the comparison
      Since:
        1.0

    - #### public int compareTo(Number right)

      Compares two Numbers. Equality (==) for numbers dispatches to this.

      Parameters:
        `right` - another Number to compare to
      Returns:
        the comparison of both numbers
      Since:
        1.0

    - #### public Number div(Character right)

      Divide a Number by a Character. The ordinal value of the Character is used in the division (the ordinal value is the unicode value which for simple character sets is the ASCII value).

      Parameters:
        `right` - a Character
      Returns:
        the Number corresponding to the division of left by right
      Since:
        1.0

    - #### public Number div(Number right)

      Divide two Numbers. Note: Method name different from 'divide' to avoid collision with BigInteger method that has different semantics. We want a BigDecimal result rather than a BigInteger.

      Parameters:
        `right` - another Number
      Returns:
        a Number resulting of the divide operation

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

      Iterates from this number down to the given number, inclusive, decrementing by one each time.

      Parameters:
        `to` - another Number to go down to
        `closure` - the closure to call
      Since:
        1.0

    - #### public Number intdiv(Character right)

      Integer Divide a Number by a Character. The ordinal value of the Character is used in the division (the ordinal value is the unicode value which for simple character sets is the ASCII value).

      Parameters:
        `right` - a Character
      Returns:
        a Number (an Integer) resulting from the integer division operation
      Since:
        1.0

    - #### public Number intdiv(Number right)

      Integer Divide two Numbers.

      Parameters:
        `right` - another Number
      Returns:
        a Number (an Integer) resulting from the integer division operation
      Since:
        1.0

    - #### public boolean isCase(Number switchValue)

      Special 'case' implementation for all numbers, which delegates to the `compareTo()` method for comparing numbers of different types.

      Parameters:
        `switchValue` - the switch value
      Returns:
        true if the numbers are deemed equal
      Since:
        1.5.0

    - #### public boolean isNotCase(Number switchValue)

      Since:
        4.0.0

    - #### public Number leftShift(Number operand)

      Implementation of the left shift operator for integral types. Non-integral Number types throw UnsupportedOperationException.

      Parameters:
        `operand` - the shift distance by which to left shift the number
      Returns:
        the resulting number
      Since:
        1.5.0

    - #### public Number minus(Character right)

      Subtract a Character from a Number. The ordinal value of the Character is used in the subtraction (the ordinal value is the unicode value which for simple character sets is the ASCII value).

      Parameters:
        `right` - a Character
      Returns:
        the Number corresponding to the subtraction of right from left
      Since:
        1.0

    - #### public Number minus(Number right)

      Subtraction of two Numbers.

      Parameters:
        `right` - another Number to subtract to the first one
      Returns:
        the subtraction

    - #### public Number mod(Number right)

      Performs a division modulus operation.

      Parameters:
        `right` - another Number to mod
      Returns:
        the modulus result
      Since:
        1.0

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

      Multiply a Number by a Character. The ordinal value of the Character is used in the multiplication (the ordinal value is the unicode value which for simple character sets is the ASCII value).

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

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

    - #### public Number next()

      Increment a Number by one.

      Returns:
        an incremented Number
      Since:
        1.0

    - #### public Number or(Number right)

      Bitwise OR together two numbers.

      Parameters:
        `right` - another Number to bitwise OR
      Returns:
        the bitwise OR of both Numbers
      Since:
        1.0

    - #### public Number plus(Character right)

      Add a Number and a Character. The ordinal value of the Character is used in the addition (the ordinal value is the unicode value which for simple character sets is the ASCII value).

      Parameters:
        `right` - a Character
      See Also:
        Integer.valueOf
      Returns:
        The Number corresponding to the addition of left and right
      Since:
        1.0

    - #### public String plus(String right)

      Appends a String to the string representation of this number.

      Parameters:
        `right` - a String
      Returns:
        a String
      Since:
        1.0

    - #### public Number plus(Number right)

      Add two numbers and return the result.

      Parameters:
        `right` - another Number to add
      Returns:
        the addition of both Numbers

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

      Power of a Number to a certain exponent. Called by the '**' operator.

      Parameters:
        `exponent` - a Number exponent
      Returns:
        a Number to the power of a certain exponent
      Since:
        1.0

    - #### public Number previous()

      Decrement a Number by one.

      Returns:
        a decremented Number
      Since:
        1.0

    - #### public Number remainder(Number right)

      Performs a division modulus operation. Called by the '%' operator.

      Parameters:
        `right` - another Number to find the remainder
      Returns:
        the remainder result
      Since:
        5.0.0

    - #### public Number rightShift(Number operand)

      Implementation of the right shift operator for integral types. Non-integral Number types throw UnsupportedOperationException.

      Parameters:
        `operand` - the shift distance by which to right shift the number
      Returns:
        the resulting number
      Since:
        1.5.0

    - #### public Number rightShiftUnsigned(Number operand)

      Implementation of the right shift (unsigned) operator for integral types. Non-integral Number types throw UnsupportedOperationException.

      Parameters:
        `operand` - the shift distance by which to right shift (unsigned) the number
      Returns:
        the resulting number
      Since:
        1.5.0

    - #### public void step(Number to, Number stepNumber, Closure closure)

      Iterates from this number up to the given number using a step increment. Each intermediate number is passed to the given closure. Example:

           0.step( 10, 2 ) {
             println it
           }

      Prints even numbers 0 through 8.
      Parameters:
        `to` - a Number to go up to, exclusive
        `stepNumber` - a Number representing the step increment
        `closure` - the closure to call
      Since:
        1.0

    - #### public void times(Closure closure)

      Executes the closure this many times, starting from zero. The current index is passed to the closure each time. Example:

          10.times {
             println it
           }

      Prints the numbers 0 through 9.
      Parameters:
        `closure` - the closure to call a number of times
      Since:
        1.0

    - #### public BigDecimal toBigDecimal()

      Transforms a Number into a BigDecimal.

      Returns:
        a BigDecimal
      Since:
        1.0

    - #### public BigInteger toBigInteger()

      Transforms this Number into a BigInteger.

      Returns:
        a BigInteger
      Since:
        1.0

    - #### public String toCurrencyString()

      Formats a Number as a currency String using Locale.getDefault. This is intended for human-facing output in single-user contexts such as a CLI or desktop application. In a server or other multi-tenant context, the default locale is the container's, not the end user's, so prefer Number.toCurrencyString with an explicit locale.

      Returns:
        the currency-formatted String
      See Also:
        toCurrencyString(Number, Locale)
        NumberFormat.getCurrencyInstance
      Since:
        6.0.0

    - #### public String toCurrencyString(Locale locale)

      Formats a Number as a currency String using the given locale.

           assert 1234.5.toCurrencyString(Locale.US) == '$1,234.50'

      Parameters:
        `locale` - the locale defining the currency format
      Returns:
        the currency-formatted String
      See Also:
        StringGroovyMethods#toCurrencyNumber(CharSequence, Locale)#toCurrencyNumber(CharSequence, Locale)
        NumberFormat.getCurrencyInstance
      Since:
        6.0.0

    - #### public Double toDouble()

      Transforms a Number into a Double.

      Returns:
        a Double
      Since:
        1.0

    - #### public Float toFloat()

      Transforms a Number into a Float.

      Returns:
        a Float
      Since:
        1.0

    - #### public Integer toInteger()

      Transforms a Number into an Integer.

      Returns:
        an Integer
      Since:
        1.0

    - #### public Long toLong()

      Transforms a Number into a Long.

      Returns:
        a Long
      Since:
        1.0

    - #### public String toPercentString()

      Formats a Number as a percent String using Locale.getDefault. The value is scaled by 100 and, by default, rounded to whole percent (e.g. `0.945` becomes `94%`). This is intended for human-facing output in single-user contexts such as a CLI or desktop application. In a server or other multi-tenant context, the default locale is the container's, not the end user's, so prefer Number.toPercentString with an explicit locale.

      Returns:
        the percent-formatted String
      See Also:
        toPercentString(Number, Locale)
        NumberFormat.getPercentInstance
      Since:
        6.0.0

    - #### public String toPercentString(Locale locale)

      Formats a Number as a percent String using the given locale. The value is scaled by 100 and, by default, rounded to whole percent.

           assert 0.5.toPercentString(Locale.US) == '50%'
           assert 0.945.toPercentString(Locale.US) == '94%' // rounded, not '94.5%'

      For fraction digits, format via NumberFormat.getPercentInstance with NumberFormat.setMaximumFractionDigits.
      Parameters:
        `locale` - the locale defining the percent format
      Returns:
        the percent-formatted String
      See Also:
        StringGroovyMethods#toPercentNumber(CharSequence, Locale)#toPercentNumber(CharSequence, Locale)
        NumberFormat.getPercentInstance
      Since:
        6.0.0

    - #### public Number unaryMinus()

      Negates the number. Equivalent to the '-' operator when it precedes a single operand, i.e. `-10`

      Returns:
        the negation of the number
      Since:
        1.5.0

    - #### public Number unaryPlus()

      Returns the number, effectively being a noop for numbers. Operator overloaded form of the '+' operator when it precedes a single operand, i.e. `+10`

      Returns:
        the number
      Since:
        2.2.0

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

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

      Parameters:
        `to` - another Number to go up to
        `closure` - the closure to call
      Since:
        1.0

    - #### public Number xor(Number right)

      Bitwise XOR together two Numbers. Called when the '^' operator is used.

      Parameters:
        `right` - another Number to bitwise XOR
      Returns:
        the bitwise XOR of both Numbers
      Since:
        1.0