Package org.openjdk.jmc.common.unit

Interface IQuantity

All Superinterfaces:
Comparable<IQuantity>, IDisplayable, IItem
All Known Subinterfaces:
ITypedQuantity<U>
public interface IQuantity extends IItem, IDisplayable, Comparable<IQuantity>

  • Field Summary

    Fields inherited from interface org.openjdk.jmc.common.IDisplayable

    AUTO, EXACT, VERBOSE

  • Method Summary

    Modifier and Type
    Method
    Description
    IQuantity
    add(IQuantity addend)
    Returns a new quantity that is the arithmetic sum of this quantity and addend, if such an operation is defined for this kind of quantity.
    long
    clampedFloorIn(IUnit targetUnit)
    Get the long value closest to the floor of the numerical quantity value that this quantity would have if expressed in the unit targetUnit.
    int
    clampedIntFloorIn(IUnit targetUnit)
    Get the int value closest to the floor of the numerical quantity value that this quantity would have if expressed in the unit targetUnit.
    long
    clampedLongValueIn(IUnit targetUnit)
    Get the long value closest to the numerical quantity value that this quantity would have if expressed in the unit targetUnit.
    double
    doubleValue()
    Get the numerical quantity value of this quantity as a double.
    double
    doubleValueIn(IUnit targetUnit)
    Get the numerical quantity value that this quantity would have if expressed in the unit targetUnit, as a double.
    KindOfQuantity<?>
    getType()
    Get the kind of this quantity.
    IUnit
    getUnit()
     
    IQuantity
    in(IUnit targetUnit)
    Get this quantity expressed in the unit targetUnit.
    String
    interactiveFormat()
    An exact string representation taking locale and internationalization into account.
    boolean
    isLinear()
    If this quantity is linear.
    long
    longValue()
    Get the numerical quantity value of this quantity as a long.
    long
    longValueIn(IUnit targetUnit)
    Get the numerical quantity value that this quantity would have if expressed in the unit targetUnit, rounded to a mathematical integer, if that numerical value can be represented in a long.
    long
    longValueIn(IUnit targetUnit, long maxAbsValue)
    Get the numerical quantity value that this quantity would have if expressed in the unit targetUnit, rounded to a mathematical integer, if that numerical value is in the range [-maxAbsValue-1, maxAbsValue].
    IQuantity
    multiply(double factor)
    Returns a new quantity that is this quantity multiplied with factor, if this is a linear quantity.
    IQuantity
    multiply(long factor)
    Returns a new quantity that is this quantity multiplied with factor, if this is a linear quantity.
    Number
    numberValue()
    Get the numerical quantity value that this quantity, as either a Long or a Number with at least the precision of double.
    Number
    numberValueIn(IUnit targetUnit)
    Get the numerical quantity value that this quantity would have if expressed in the unit targetUnit, as either a Long or a Number with at least the precision of double.
    String
    persistableString()
    A string representation independent of locale or internationalization, that when parsed using KindOfQuantity.parsePersisted(String) (by this quantity's kind of quantity) yields a value that is equal to this quantity.
    double
    ratioTo(IQuantity consequent)
    Compute the ratio of this quantity to the given consequent quantity, if both are of the same linear kind.
    IQuantity
    subtract(IQuantity subtrahend)
    Returns a new quantity that is the arithmetic difference of this quantity and subtrahend, if such an operation is defined for this kind of quantity.

    Methods inherited from interface java.lang.Comparable

    compareTo

    Methods inherited from interface org.openjdk.jmc.common.IDisplayable

    displayUsing

  • Method Details

    • getType

      KindOfQuantity<?> getType()
      Get the kind of this quantity.
      Specified by:
      getType in interface IItem
      Returns:
      the type of this item

    • getUnit

      IUnit getUnit()
      Returns:
      the unit in which this quantity is expressed

    • in

      IQuantity in(IUnit targetUnit)
      Get this quantity expressed in the unit targetUnit. Note that as a result of this conversion, precision may be lost. Partly due to that fact, this method should generally not be used. If the ultimate goal is some pure numerical value, there are more suitable methods, some of which are listed below, which directly provides such values. In either case, the quantity returned from this method should not be kept alive, as the original quantity provides better precision.
      Returns:
      a quantity, with approximately the same value as this quantity, expressed in targetUnit
      Throws:
      IllegalArgumentException - if targetUnit is not of the same kind of quantity
      See Also:

    • longValueIn

      long longValueIn(IUnit targetUnit, long maxAbsValue) throws QuantityConversionException
      Get the numerical quantity value that this quantity would have if expressed in the unit targetUnit, rounded to a mathematical integer, if that numerical value is in the range [-maxAbsValue-1, maxAbsValue]. Otherwise, an QuantityConversionException will be thrown, with the violation encoded. Note that as a result of this conversion, precision may be lost.
      Returns:
      the numerical quantity, as a long
      Throws:
      QuantityConversionException - if the result would be out of range
      IllegalArgumentException - if targetUnit is not of the same kind of quantity
      See Also:

    • longValueIn

      long longValueIn(IUnit targetUnit) throws QuantityConversionException
      Get the numerical quantity value that this quantity would have if expressed in the unit targetUnit, rounded to a mathematical integer, if that numerical value can be represented in a long. Otherwise, an QuantityConversionException will be thrown, with the violation encoded. Note that as a result of this conversion, precision may be lost.

      This method is equivalent to longValueIn(IUnit, Long.MAX_VALUE).

      Returns:
      the numerical quantity, as a long
      Throws:
      QuantityConversionException - if the result would be out of range
      IllegalArgumentException - if targetUnit is not of the same kind of quantity
      See Also:

    • clampedLongValueIn

      long clampedLongValueIn(IUnit targetUnit)
      Get the long value closest to the numerical quantity value that this quantity would have if expressed in the unit targetUnit. This means that values outside the range [ Long.MIN_VALUE ,Long.MAX_VALUE] will be clamped to the closest extreme. Note that as a result of this conversion, precision may be lost.

      This method is equivalent to in(IUnit)@.longValue(), but is preferred since it is both cheaper and its name more explicitly conveys the limitations involved.

      Returns:
      the numerical quantity, as a long
      Throws:
      IllegalArgumentException - if targetUnit is not of the same kind of quantity
      See Also:

    • clampedFloorIn

      long clampedFloorIn(IUnit targetUnit)
      Get the long value closest to the floor of the numerical quantity value that this quantity would have if expressed in the unit targetUnit. This means that values outside the range[ Long.MIN_VALUE , Long.MAX_VALUE ] will be clamped to the closest extreme. Note that as a result of this conversion, precision may be lost.
      Returns:
      the floor of the numerical quantity, as a long
      Throws:
      IllegalArgumentException - if targetUnit is not of the same kind of quantity

    • clampedIntFloorIn

      int clampedIntFloorIn(IUnit targetUnit)
      Get the int value closest to the floor of the numerical quantity value that this quantity would have if expressed in the unit targetUnit. This means that values outside the range[ Integer.MIN_VALUE , Integer.MAX_VALUE ] will be clamped to the closest extreme. Note that as a result of this conversion, precision may be lost.
      Returns:
      the floor of the numerical quantity, as an int
      Throws:
      IllegalArgumentException - if targetUnit is not of the same kind of quantity

    • doubleValueIn

      double doubleValueIn(IUnit targetUnit)
      Get the numerical quantity value that this quantity would have if expressed in the unit targetUnit, as a double. Note that as a result of this conversion, precision may be lost.
      Returns:
      the numerical quantity, as a double
      Throws:
      IllegalArgumentException - if targetUnit is not of the same kind of quantity

    • numberValueIn

      Number numberValueIn(IUnit targetUnit)
      Get the numerical quantity value that this quantity would have if expressed in the unit targetUnit, as either a Long or a Number with at least the precision of double. If this quantity is exact, the unit conversion is known to be exact, and the result can be exactly represented in a long, a Long will be returned. Otherwise, some other Number implementation, such as Double will be returned. Note that as a result of this conversion, precision may be lost.
      Returns:
      the numerical quantity, as a Long if exact, otherwise as some other Number
      Throws:
      IllegalArgumentException - if targetUnit is not of the same kind of quantity
      See Also:

    • longValue

      long longValue()
      Get the numerical quantity value of this quantity as a long. This may cause truncation and loss of precision.
      Returns:
      the numerical quantity, as a long

    • doubleValue

      double doubleValue()
      Get the numerical quantity value of this quantity as a double. This may cause loss of precision.
      Returns:
      the numerical quantity, as a double

    • numberValue

      Number numberValue()
      Get the numerical quantity value that this quantity, as either a Long or a Number with at least the precision of double.
      Returns:
      the numerical quantity

    • persistableString

      String persistableString()
      A string representation independent of locale or internationalization, that when parsed using KindOfQuantity.parsePersisted(String) (by this quantity's kind of quantity) yields a value that is equal to this quantity. That is, the exact representation must be preserved.
      Returns:
      a string representation independent of locale or internationalization.

    • interactiveFormat

      String interactiveFormat()
      An exact string representation taking locale and internationalization into account. When parsed using KindOfQuantity.parseInteractive(String) (by this quantity's kind of quantity), in the same locale, yields a value that is equal to this quantity. That is, the exact representation must be preserved.
      Returns:
      a string representation taking locale and internationalization into account.

    • isLinear

      boolean isLinear()
      If this quantity is linear. That is, if quantities of the same kind can be added to and subtracted from it, and the resulting quantity remains of the same kind.
      Returns:
      true iff the quantity is linear

    • add

      IQuantity add(IQuantity addend) throws IllegalArgumentException
      Returns a new quantity that is the arithmetic sum of this quantity and addend, if such an operation is defined for this kind of quantity. This operation is commutative, so that a.add(b) produces the same result, or throws the same kind of exception, as b.add(a).

      Note that if this quantity is linear, adding a quantity of the same kind is guaranteed to succeed and produces a quantity of the same kind. Also, the sum of a non-linear quantity and a linear quantity of a specific related (delta) kind of quantity is defined and produces a non-linear quantity. However, two non-linear quantities may never be added.

      Returns:
      the sum of this quantity and addend
      Throws:
      IllegalArgumentException - if addend is not of a compatible kind of quantity

    • subtract

      IQuantity subtract(IQuantity subtrahend) throws IllegalArgumentException
      Returns a new quantity that is the arithmetic difference of this quantity and subtrahend, if such an operation is defined for this kind of quantity. This operation is anti-commutative when this quantity and subtrahend are of the same kind. That is, when the result is linear.

      Quantities of the same kind may be subtracted, giving a linear result. Additionally, a linear quantity may be subtracted from a non-linear quantity, provided their kinds are related.

      Returns:
      the difference of this quantity and subtrahend
      Throws:
      IllegalArgumentException - if subtrahend is not of a compatible kind of quantity

    • multiply

      IQuantity multiply(long factor) throws UnsupportedOperationException
      Returns a new quantity that is this quantity multiplied with factor, if this is a linear quantity. Otherwise, this operation is undefined and UnsupportedOperationException will be thrown.
      Returns:
      this quantity multiplied with factor
      Throws:
      UnsupportedOperationException - if this quantity is not linear

    • multiply

      IQuantity multiply(double factor) throws UnsupportedOperationException
      Returns a new quantity that is this quantity multiplied with factor, if this is a linear quantity. Otherwise, this operation is undefined and UnsupportedOperationException will be thrown.
      Returns:
      this quantity multiplied with factor
      Throws:
      UnsupportedOperationException - if this quantity is not linear

    • ratioTo

      double ratioTo(IQuantity consequent) throws UnsupportedOperationException, IllegalArgumentException
      Compute the ratio of this quantity to the given consequent quantity, if both are of the same linear kind. Otherwise, this operation is undefined and an exception is thrown.
      Returns:
      the ratio of this quantity to consequent, as a double fraction
      Throws:
      UnsupportedOperationException - if this quantity is not linear
      IllegalArgumentException - if consequent is not of a compatible kind of quantity