Units of Measurement API 2.2 · javax.measure.Quantity

Represents a quantitative property of a phenomenon, body, or substance, that can be quantified by measurement. Mass, time, distance, heat, and angular separation are among the familiar examples of quantitative properties.

Unit<Mass> pound = ... Quantity<Length> size = ... Sensor<Temperature> thermometer = ... Vector3D<Speed> aircraftSpeed = ...

Arithmetic operations

This interface defines some arithmetic operations between Quantity instances. All implementations shall produce equivalent results for the same operation applied on equivalent quantities. Two quantities are equivalent if, after conversion to the same unit of measurement, they have the same numerical value (ignoring rounding errors). For example 2000 metres is equivalent to 2 km, but 2°C is not equivalent to 2 K; it is equivalent to 275.15 K instead. Above requirement applied to addition means that 2°C + 2 K shall be equivalent to 275.15 K + 2 K.

All operations shall preserve the basic laws of algebra, in particular commutativity of addition and multiplication (A + B = B + A) and associativity of addition and multiplication (A + B) + C = A + (B + C). In order to preserve those algebra laws, this specification requires all arithmetic operations to execute as is all operands were converted to system unit before the operation is carried out, and the result converted back to any compatible unit at implementation choice. For example 4 cm + 1 inch shall produce any result equivalent to 0.04 m + 0.0254 m.

Implementations are allowed to avoid conversion to system unit if the result is guaranteed to be equivalent. This is often the case when the conversion between quantity unit and system unit is only a scale factor. However this is not the case for conversions applying an offset or more complex formula. For example 2°C + 1°C = 274.15°C, not 3°C. This counter-intuitive result is essential for preserving algebra laws like associativity, and is also the expected result from a thermodynamic point of view.

API Note:: This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended. All implementations must be Comparable.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	Quantity.Scale The scale of a `Quantity`, either `ABSOLUTE` or `RELATIVE`.

Method Summary

Modifier and Type	Method and Description
public Quantity<Q>	Returns: `this + addend`. add(Quantity<Q> the `Quantity` to be added. addend) Returns the sum of this `Quantity` with the one specified.
public < The type of the quantity. T extends Quantity<T>> Quantity<T>	Returns: this quantity parameterized with the specified type. asType(Class<T> the quantity class identifying the nature of the quantity. type) Casts this quantity to a parameterized unit of specified nature or throw a `ClassCastException` if the dimension of the specified quantity and this measure unit's dimension do not match.
public Quantity<?>	Returns: `this / divisor`. divide(Quantity<?> the `Quantity` divisor. divisor) Returns the quotient of this `Quantity` divided by the `Quantity` specified.
public Quantity<Q>	Returns: `this / divisor`. divide(Number the `Number` divisor. divisor) Returns the quotient of this `Quantity` divided by the `Number` specified.
public Quantity.Scale	Returns: the scale, if it's an absolute or relative quantity. getScale() Returns the `Scale` of this `Quantity`, if it's absolute or relative.
public Unit<Q>	Returns: the unit (shall not be `null`). getUnit() Returns the unit of this `Quantity`.
public Number	Returns: a value. getValue() Returns the value of this `Quantity`.
public Quantity<?>	Returns: reciprocal `Quantity` inverse() Returns a `Quantity` that is the multiplicative inverse of this `Quantity`, having reciprocal value and reciprocal unit as given by `this.getUnit().inverse()`.
public boolean	Returns: `true` if `that ≡ this`. isEquivalentTo(Quantity<Q> the `quantity<Q>` to be compared with this instance. that) Compares two instances of `Quantity <Q>`, performing the conversion of units if necessary.
public Quantity<?>	Returns: `this * multiplicand`. multiply(Quantity<?> the `Quantity` multiplicand. multiplicand) Returns the product of this `Quantity` with the one specified.
public Quantity<Q>	Returns: `this * multiplicand`. multiply(Number the `Number` multiplicand. multiplicand) Returns the product of this `Quantity` with the `Number` value specified.
public Quantity<Q>	Returns: `-this`. negate() Returns a `Quantity` whose value is `(-this.getValue())`.
public Quantity<Q>	Returns: `this - subtrahend`. subtract(Quantity<Q> the `Quantity` to be subtracted. subtrahend) Returns the difference between this `Quantity` and the one specified.
public Quantity<Q>	Returns: this quantity or a new quantity equivalent to this quantity stated in the specified unit. to(Unit<Q> the `Unit unit` in which the returned quantity is stated. unit) Returns this `Quantity` converted into another (compatible) `Unit`.
public default Quantity<Q>	Returns: this quantity or a new quantity equivalent to this quantity stated in SI units. toSystemUnit() Convenient method equivalent to `to(getUnit().toSystemUnit())`.

Method Detail

add back to summary

add	back to summary
public Quantity<Q> add(Quantity<Q> addend) Returns the sum of this `Quantity` with the one specified. The result shall be as if this quantity and the given addend were converted to system unit before to be added, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice. Parameters addend:Quantity<Q> the `Quantity` to be added. Returns:Quantity<Q> `this + addend`.

public Quantity<Q> add(Quantity<Q> addend)

Returns the sum of this Quantity with the one specified. The result shall be as if this quantity and the given addend were converted to system unit before to be added, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice.

Parameters

addend:Quantity<Q>: the Quantity to be added.

Returns:Quantity<Q>

this + addend.

asType back to summary

asType	back to summary
public <T extends Quantity<T>> Quantity<T> asType(Class<T> type) throws ClassCastException Casts this quantity to a parameterized unit of specified nature or throw a `ClassCastException` if the dimension of the specified quantity and this measure unit's dimension do not match. For example: `Quantity<Length> length = Quantities.getQuantity("2 km").asType(Length.class);` or `Quantity<Speed> C = length.multiply(299792458).divide(second).asType(Speed.class);` Parameters <T> The type of the quantity. type:Class<T> the quantity class identifying the nature of the quantity. Returns:Quantity<T> this quantity parameterized with the specified type. Exceptions ClassCastException: if the dimension of this unit is different from the specified quantity dimension. UnsupportedOperationException: if the specified quantity class does not have a SI unit for the quantity. See Also `Unit#asType(Class)`

public <T extends Quantity<T>> Quantity<T> asType(Class<T> type) throws ClassCastException

Casts this quantity to a parameterized unit of specified nature or throw a ClassCastException if the dimension of the specified quantity and this measure unit's dimension do not match. For example:

Quantity<Length> length = Quantities.getQuantity("2 km").asType(Length.class); or Quantity<Speed> C = length.multiply(299792458).divide(second).asType(Speed.class);

Parameters

<T>: The type of the quantity.
type:Class<T>: the quantity class identifying the nature of the quantity.

Returns:Quantity<T>

this quantity parameterized with the specified type.

Exceptions

ClassCastException:: if the dimension of this unit is different from the specified quantity dimension.
UnsupportedOperationException:: if the specified quantity class does not have a SI unit for the quantity.

See Also

Unit#asType(Class)

divide back to summary

divide	back to summary
public Quantity<?> divide(Quantity<?> divisor) Returns the quotient of this `Quantity` divided by the `Quantity` specified. The result shall be as if this quantity and the given divisor were converted to system unit before to be divided, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice. Parameters divisor:Quantity<?> the `Quantity` divisor. Returns:Quantity<?> `this / divisor`. Exceptions ClassCastException: if the type of an element in the specified operation is incompatible with this quantity

public Quantity<?> divide(Quantity<?> divisor)

Returns the quotient of this Quantity divided by the Quantity specified. The result shall be as if this quantity and the given divisor were converted to system unit before to be divided, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice.

Parameters

divisor:Quantity<?>: the Quantity divisor.

Returns:Quantity<?>

this / divisor.

Exceptions

ClassCastException:: if the type of an element in the specified operation is incompatible with this quantity

divide back to summary

divide	back to summary
public Quantity<Q> divide(Number divisor) Returns the quotient of this `Quantity` divided by the `Number` specified. The result shall be as if this quantity was converted to system unit before to be divided, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice. Parameters divisor:Number the `Number` divisor. Returns:Quantity<Q> `this / divisor`.

public Quantity<Q> divide(Number divisor)

Returns the quotient of this Quantity divided by the Number specified. The result shall be as if this quantity was converted to system unit before to be divided, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice.

Parameters

divisor:Number: the Number divisor.

Returns:Quantity<Q>

this / divisor.

getScale back to summary

getScale	back to summary
public Quantity.Scale getScale() Returns the `Scale` of this `Quantity`, if it's absolute or relative. Returns:Quantity.Scale the scale, if it's an absolute or relative quantity. Since 2.0 See Also Wikipedia: Absolute scale

public Quantity.Scale getScale()

Returns the Scale of this Quantity, if it's absolute or relative.

Returns:Quantity.Scale: the scale, if it's an absolute or relative quantity.
Since: 2.0
See Also: Wikipedia: Absolute scale

getUnit back to summary

getUnit	back to summary
public Unit<Q> getUnit() Returns the unit of this `Quantity`. Returns:Unit<Q> the unit (shall not be `null`).

public Unit<Q> getUnit()

Returns the unit of this Quantity.

Returns:Unit<Q>: the unit (shall not be null).

getValue back to summary

getValue	back to summary
public Number getValue() Returns the value of this `Quantity`. Returns:Number a value.

public Number getValue()

Returns the value of this Quantity.

Returns:Number: a value.

inverse back to summary

inverse	back to summary
public Quantity<?> inverse() Returns a `Quantity` that is the multiplicative inverse of this `Quantity`, having reciprocal value and reciprocal unit as given by `this.getUnit().inverse()`. Returns:Quantity<?> reciprocal `Quantity` See Also Wikipedia: Multiplicative inverse

public Quantity<?> inverse()

Returns a Quantity that is the multiplicative inverse of this Quantity, having reciprocal value and reciprocal unit as given by this.getUnit().inverse().

Returns:Quantity<?>: reciprocal Quantity
See Also: Wikipedia: Multiplicative inverse

isEquivalentTo back to summary

isEquivalentTo	back to summary
public boolean isEquivalentTo(Quantity<Q> that) Compares two instances of `Quantity <Q>`, performing the conversion of units if necessary. Parameters that:Quantity<Q> the `quantity<Q>` to be compared with this instance. Returns:boolean `true` if `that ≡ this`. Exceptions NullPointerException: if the quantity is null Since 2.1 See Also Cambridge Dictionary: equivalent, LEXICO: equivalent

public boolean isEquivalentTo(Quantity<Q> that)

Compares two instances of Quantity <Q>, performing the conversion of units if necessary.

Parameters

that:Quantity<Q>: the quantity<Q> to be compared with this instance.

Returns:boolean

true if that ≡ this.

Exceptions

NullPointerException:: if the quantity is null

Since

2.1

multiply back to summary

multiply	back to summary
public Quantity<?> multiply(Quantity<?> multiplicand) Returns the product of this `Quantity` with the one specified. The result shall be as if this quantity and the given multiplicand were converted to system unit before to be multiplied, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice. Parameters multiplicand:Quantity<?> the `Quantity` multiplicand. Returns:Quantity<?> `this * multiplicand`. Exceptions ClassCastException: if the type of an element in the specified operation is incompatible with this quantity

public Quantity<?> multiply(Quantity<?> multiplicand)

Returns the product of this Quantity with the one specified. The result shall be as if this quantity and the given multiplicand were converted to system unit before to be multiplied, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice.

Parameters

multiplicand:Quantity<?>: the Quantity multiplicand.

Returns:Quantity<?>

this * multiplicand.

Exceptions

ClassCastException:: if the type of an element in the specified operation is incompatible with this quantity

multiply back to summary

multiply	back to summary
public Quantity<Q> multiply(Number multiplicand) Returns the product of this `Quantity` with the `Number` value specified. The result shall be as if this quantity was converted to system unit before to be multiplied, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice. Parameters multiplicand:Number the `Number` multiplicand. Returns:Quantity<Q> `this * multiplicand`.

public Quantity<Q> multiply(Number multiplicand)

Returns the product of this Quantity with the Number value specified. The result shall be as if this quantity was converted to system unit before to be multiplied, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice.

Parameters

multiplicand:Number: the Number multiplicand.

Returns:Quantity<Q>

this * multiplicand.

negate back to summary

negate	back to summary
public Quantity<Q> negate() Returns a `Quantity` whose value is `(-this.getValue())`. Returns:Quantity<Q> `-this`.

public Quantity<Q> negate()

Returns a Quantity whose value is (-this.getValue()).

Returns:Quantity<Q>: -this.

subtract back to summary

subtract	back to summary
public Quantity<Q> subtract(Quantity<Q> subtrahend) Returns the difference between this `Quantity` and the one specified. The result shall be as if this quantity and the given subtrahend were converted to system unit before to be subtracted, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice. Parameters subtrahend:Quantity<Q> the `Quantity` to be subtracted. Returns:Quantity<Q> `this - subtrahend`.

public Quantity<Q> subtract(Quantity<Q> subtrahend)

Returns the difference between this Quantity and the one specified. The result shall be as if this quantity and the given subtrahend were converted to system unit before to be subtracted, and the result converted back to the unit of this quantity or any other compatible unit at implementation choice.

Parameters

subtrahend:Quantity<Q>: the Quantity to be subtracted.

Returns:Quantity<Q>

this - subtrahend.

to back to summary

to	back to summary
public Quantity<Q> to(Unit<Q> unit) Returns this `Quantity` converted into another (compatible) `Unit`. Parameters unit:Unit<Q> the `Unit unit` in which the returned quantity is stated. Returns:Quantity<Q> this quantity or a new quantity equivalent to this quantity stated in the specified unit. Exceptions ArithmeticException: if the result is inexact and the quotient has a non-terminating decimal expansion.

public Quantity<Q> to(Unit<Q> unit)

Returns this Quantity converted into another (compatible) Unit.

Parameters

unit:Unit<Q>: the Unit unit in which the returned quantity is stated.

Returns:Quantity<Q>

this quantity or a new quantity equivalent to this quantity stated in the specified unit.

Exceptions

ArithmeticException:: if the result is inexact and the quotient has a non-terminating decimal expansion.

toSystemUnit back to summary

toSystemUnit	back to summary
public default Quantity<Q> toSystemUnit() Convenient method equivalent to `to(getUnit().toSystemUnit())`. Returns:Quantity<Q> this quantity or a new quantity equivalent to this quantity stated in SI units. Exceptions ArithmeticException: if the result is inexact and the quotient has a non-terminating decimal expansion.

public default Quantity<Q> toSystemUnit()

Convenient method equivalent to to(getUnit().toSystemUnit()).

Returns:Quantity<Q>

this quantity or a new quantity equivalent to this quantity stated in SI units.

Exceptions

ArithmeticException:: if the result is inexact and the quotient has a non-terminating decimal expansion.

Modifier and Type	Field and Description
public static final Quantity.Scale	ABSOLUTE Absolute scale
public static final Quantity.Scale	RELATIVE Relative scale

Modifier and Type	Method and Description
public static Quantity.Scale	valueOf(String name)
public static Quantity.Scale[]	values()

public Interface Quantity<Q extends javax.measure.Quantity<Q>>

Nested and Inner Type Summary

Method Summary

Method Detail

public final Enum Quantity.Scale

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail