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 and 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 org.openjdk.jmc.common.IDisplayable

displayUsing

Methods inherited from interface java.lang.Comparable

compareTo

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)

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:

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

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