Package org.openjdk.jmc.common.unit

Interface IQuantity

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      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.

    • Method Detail

      • 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:
        doubleValueIn(IUnit), numberValueIn(IUnit), clampedLongValueIn(IUnit), ratioTo(IQuantity)

      • 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:
        numberValueIn(IUnit)

      • 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:
        numberValueIn(IUnit)

      • 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:
        clampedLongValueIn(IUnit)

      • 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