org.modeshape.common.math

## Interface MathOperations<T>

- Type Parameters:
    `T` - the numeric class, usually a subclass of `Number` (although this is not required)
  All Known Implementing Classes:
    DoubleOperations, DurationOperations, FloatOperations, IntegerOperations, LongOperations, ShortOperations

      @Immutable
      public interface MathOperations<T>

  The set of mathematic operations for a particular class of values. This is useful for generic classes that must work with one of the `Number` subclasses.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `T` | `add(T value1, T value2)` Add the two operands and return the sum.
    `BigDecimal` | `asBigDecimal(T value)` Create a `BigDecimal` representation of the supplied value.
    `int` | `compare(T value1, T value2)` Compare the two operands and return an integer that describes whether the first value is larger, smaller or the same as the second value.
    `T` | `create(double value)` Convert the double representation into the natural object representation.
    `T` | `create(int value)` Convert the integer representation into the natural object representation.
    `T` | `create(long value)` Convert the long representation into the natural object representation.
    `T` | `createZeroValue()` Create the object form of the "zero value".
    `double` | `divide(T value1, T value2)` Divide the first operand by the second, and return the result.
    `double` | `doubleValue(T value)` Convert the value to a double.
    `float` | `floatValue(T value)` Convert the value to a float.
    `T` | `fromBigDecimal(BigDecimal value)` Convert the `BigDecimal` representation into the natural object representation.
    `Comparator<T>` | `getComparator()` Return a `Comparator` for this `operand class`.
    `int` | `getExponentInScientificNotation(T value)` Get the exponent if the number were written in exponential form.
    `Class<T>` | `getOperandClass()` Return the class that these operations operate upon.
    `T` | `increment(T value)` Increment the supplied operand by 1.
    `int` | `intValue(T value)` Convert the value to an integer.
    `T` | `keepSignificantFigures(T value, int numSigFigs)`
    `long` | `longValue(T value)` Convert the value to a long integer.
    `T` | `maximum(T value1, T value2)` Compare the two operands and return the one that is larger.
    `T` | `minimum(T value1, T value2)` Compare the two operands and return the one that is smaller.
    `T` | `multiply(T value1, T value2)` Multiply the two operands and return the product.
    `T` | `negate(T value)` Negate the supplied operand.
    `T` | `random(T minimum, T maximum, Random rng)` Generate a random instance within the specified range.
    `T` | `roundDown(T value, int decimalShift)` Round down the supplied value to the desired scale.
    `T` | `roundUp(T value, int decimalShift)` Round up the supplied value to the desired scale.
    `short` | `shortValue(T value)` Convert the value to a short.
    `double` | `sqrt(T value)` Return the square root of the supplied operand.
    `T` | `subtract(T value1, T value2)` Subtract the second operand from the first, and return the difference.

- - ### Method Detail

    - #### getOperandClass

          Class<T> getOperandClass()

      Return the class that these operations operate upon.
      Returns:
        the class

    - #### add

          T add(T value1,
              T value2)

      Add the two operands and return the sum. The `zero value` is used in place of any operand that is null.
      Parameters:
        `value1` - the first operand
        `value2` - the second operand
      Returns:
        the sum of the two operands.

    - #### subtract

          T subtract(T value1,
                   T value2)

      Subtract the second operand from the first, and return the difference. The `zero value` is used in place of any operand that is null.
      Parameters:
        `value1` - the first operand
        `value2` - the second operand
      Returns:
        the difference between the two operands.

    - #### multiply

          T multiply(T value1,
                   T value2)

      Multiply the two operands and return the product. The `zero value` is used in place of any operand that is null.
      Parameters:
        `value1` - the first operand
        `value2` - the second operand
      Returns:
        the product of the two operands.

    - #### divide

          double divide(T value1,
                      T value2)

      Divide the first operand by the second, and return the result. The `zero value` is used in place of any operand that is null.
      Parameters:
        `value1` - the first operand
        `value2` - the second operand
      Returns:
        the result of the division

    - #### negate

          T negate(T value)

      Negate the supplied operand. The `zero value` is used in place of any operand that is null.
      Parameters:
        `value` - the value that is to be negated
      Returns:
        the result of the negation

    - #### increment

          T increment(T value)

      Increment the supplied operand by 1. (Note, the exact meaning of "1" is dependent upon the particular `operand class`. The `zero value` is used in place of any operand that is null.
      Parameters:
        `value` - the value that is to be incremented
      Returns:
        the incremented value

    - #### maximum

          T maximum(T value1,
                  T value2)

      Compare the two operands and return the one that is larger. A null value is considered smaller than non-null values (including 0).
      Parameters:
        `value1` - the first operand
        `value2` - the second operand
      Returns:
        the larger of the two operands

    - #### minimum

          T minimum(T value1,
                  T value2)

      Compare the two operands and return the one that is smaller. A null value is considered larger than non-null values (including 0).
      Parameters:
        `value1` - the first operand
        `value2` - the second operand
      Returns:
        the smaller of the two operands

    - #### compare

          int compare(T value1,
                    T value2)

      Compare the two operands and return an integer that describes whether the first value is larger, smaller or the same as the second value. The semantics are identical to those of `Comparable`. The `zero value` is used in place of any operand that is null.
      Parameters:
        `value1` - the first operand
        `value2` - the second operand
      Returns:
        -1 if the first value is smaller than the second, 1 if the first value is larger than the second, or 0 if they are equal.

    - #### asBigDecimal

          BigDecimal asBigDecimal(T value)

      Create a `BigDecimal` representation of the supplied value.
      Parameters:
        `value` - the value that is to be converted to a BigDecimal
      Returns:
        the BigDecimal representation, or null if `value` is null

    - #### fromBigDecimal

          T fromBigDecimal(BigDecimal value)

      Convert the `BigDecimal` representation into the natural object representation. This may result in loss of some data (e.g., converting a decimal to an integer results in the loss of the fractional part of the number).
      Parameters:
        `value` - the BigDecimal value
      Returns:
        the natural representation, or null if `value` is null

    - #### doubleValue

          double doubleValue(T value)

      Convert the value to a double. This may result in a loss of information depending upon the `operand class`.
      Parameters:
        `value` - the value
      Returns:
        the representation as a double

    - #### floatValue

          float floatValue(T value)

      Convert the value to a float. This may result in a loss of information depending upon the `operand class`.
      Parameters:
        `value` - the value
      Returns:
        the representation as a float

    - #### intValue

          int intValue(T value)

      Convert the value to an integer. This may result in a loss of information depending upon the `operand class`.
      Parameters:
        `value` - the value
      Returns:
        the representation as an integer

    - #### shortValue

          short shortValue(T value)

      Convert the value to a short. This may result in a loss of information depending upon the `operand class`.
      Parameters:
        `value` - the value
      Returns:
        the representation as a short

    - #### longValue

          long longValue(T value)

      Convert the value to a long integer. This may result in a loss of information depending upon the `operand class`.
      Parameters:
        `value` - the value
      Returns:
        the representation as a long

    - #### createZeroValue

          T createZeroValue()

      Create the object form of the "zero value". This is often used to create an uninitialized object.
      Returns:
        the object that represents zero.

    - #### create

          T create(int value)

      Convert the integer representation into the natural object representation.
      Parameters:
        `value` - the integer value
      Returns:
        the object representation of the integer

    - #### create

          T create(long value)

      Convert the long representation into the natural object representation.
      Parameters:
        `value` - the long value
      Returns:
        the object representation of the long integer

    - #### create

          T create(double value)

      Convert the double representation into the natural object representation.
      Parameters:
        `value` - the double value
      Returns:
        the object representation of the floating point number

    - #### sqrt

          double sqrt(T value)

      Return the square root of the supplied operand.
      Parameters:
        `value` - the value whose root is to be found; may not be null or 0
      Returns:
        the square root of the value

    - #### getComparator

          Comparator<T> getComparator()

      Return a `Comparator` for this `operand class`. The implementation is free to return the same comparator instance from multiple invocations of this method.
      Returns:
        a comparator

    - #### getExponentInScientificNotation

          int getExponentInScientificNotation(T value)

      Get the exponent if the number were written in exponential form.
      Parameters:
        `value` - the value
      Returns:
        the scale

    - #### roundUp

          T roundUp(T value,
                  int decimalShift)

      Round up the supplied value to the desired scale. This process works (conceptually) by shifting the decimal point of the value by `decimalShift` places, rounding, and then shifting the decimal point of the rounded value by `-decimalShift`

      For example, consider the number 10.000354. This can be rounded to 10.0004 by calling this method and supplying the value and an "exponentToKeep" value of -4.

      Parameters:
        `value` - the value to be rounded
        `decimalShift` - the number of places the decimal point should be shifted before rounding
      Returns:
        the rounded value

    - #### roundDown

          T roundDown(T value,
                    int decimalShift)

      Round down the supplied value to the desired scale. This process works (conceptually) by shifting the decimal point of the value by `decimalShift` places, rounding, and then shifting the decimal point of the rounded value by `-decimalShift`

      For example, consider the number 10.000354. This can be rounded to 10.0003 by calling this method and supplying the value and an "exponentToKeep" value of -4.

      Parameters:
        `value` - the value to be rounded
        `decimalShift` - the number of places the decimal point should be shifted before rounding
      Returns:
        the rounded value

    - #### keepSignificantFigures

          T keepSignificantFigures(T value,
                                 int numSigFigs)

    - #### random

          T random(T minimum,
                 T maximum,
                 Random rng)

      Generate a random instance within the specified range.
      Parameters:
        `minimum` - the minimum value, or null if the `zero-value` should be used for the minimum
        `maximum` - the maximum value, or null if the `zero-value` should be used for the maximum
        `rng` - the random number generator to use
      Returns:
        an instance of the `operand class` placed within the desired range using a random distribution, or null if this class does not support generating random instances

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.