Quantity (Units of Measurement API 2.0-EDR API)

Type Parameters:

Q - The type of the quantity.

All Known Subinterfaces:

Acceleration, AmountOfSubstance, Angle, Area, CatalyticActivity, Dimensionless, ElectricCapacitance, ElectricCharge, ElectricConductance, ElectricCurrent, ElectricInductance, ElectricPotential, ElectricResistance, Energy, Force, Frequency, Illuminance, Length, LuminousFlux, LuminousIntensity, MagneticFlux, MagneticFluxDensity, Mass, Power, Pressure, RadiationDoseAbsorbed, RadiationDoseEffective, Radioactivity, SolidAngle, Speed, Temperature, Time, Volume
```
public interface Quantity<Q extends Quantity<Q>>
```
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.

Since:

1.0

Version:

1.3, August 2, 2018

Author:

Jean-Marie Dautelle, Martin Desruisseaux, Werner Keil, Otavio Santana

See Also:

Unit, Wikipedia: Quantity, Martin Fowler - Quantity

API Note:

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

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`Quantity<Q>`	`add(Quantity<Q> addend)` Returns the sum of this `Quantity` with the one specified.
`<T extends Quantity<T>> Quantity<T>`	`asType(java.lang.Class<T> 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.
`Quantity<Q>`	`divide(java.lang.Number divisor)` Returns the product of this `Quantity` divided by the `Number` specified.
`Quantity<?>`	`divide(Quantity<?> divisor)` Returns the product of this `Quantity` divided by the `Quantity` specified.
`Unit<Q>`	`getUnit()` Returns the unit of this `Quantity`.
`java.lang.Number`	`getValue()` Returns the value of this `Quantity`.
`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()`.
`Quantity<Q>`	`multiply(java.lang.Number multiplicand)` Returns the product of this `Quantity` with the `Number` value specified.
`Quantity<?>`	`multiply(Quantity<?> multiplicand)` Returns the product of this `Quantity` with the one specified.
`Quantity<Q>`	`negate()` Returns a `Quantity` whose value is `(-this.getValue())`.
`Quantity<Q>`	`subtract(Quantity<Q> subtrahend)` Returns the difference between this `Quantity` and the one specified.
`Quantity<Q>`	`to(Unit<Q> unit)` Returns this `Quantity` converted into another (compatible) `Unit`.
`default Quantity<Q>`	`toSystemUnit()` Convenient method equivalent to `to(getUnit().toSystemUnit())`.

- Method Detail
  - add
```
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 - the Quantity to be added.
    
    Returns:
    
    this + addend.
  - subtract
```
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 - the Quantity to be subtracted.
    
    Returns:
    
    this - subtrahend.
  - divide
```
Quantity<?> divide(Quantity<?> divisor)
```
    Returns the product 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 - the Quantity divisor.
    
    Returns:
    
    this / divisor.
    
    Throws:
    
    java.lang.ClassCastException - if the type of an element in the specified operation is incompatible with this quantity (optional)
  - divide
```
Quantity<Q> divide(java.lang.Number divisor)
```
    Returns the product 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 - the Number divisor.
    
    Returns:
    
    this / divisor.
  - multiply
```
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 - the Quantity multiplicand.
    
    Returns:
    
    this * multiplicand.
    
    Throws:
    
    java.lang.ClassCastException - if the type of an element in the specified operation is incompatible with this quantity (optional)
  - multiply
```
Quantity<Q> multiply(java.lang.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 - the Number multiplicand.
    
    Returns:
    
    this * multiplicand.
  - to
```
Quantity<Q> to(Unit<Q> unit)
```
    Returns this Quantity converted into another (compatible) Unit.
    
    Parameters:
    
    unit - the Unit to convert to.
    
    Returns:
    
    the converted result.
  - inverse
```
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:
    
    reciprocal Quantity
    
    See Also:
    
    Wikipedia: Multiplicative inverse
  - negate
```
Quantity<Q> negate()
```
    Returns a Quantity whose value is (-this.getValue()).
    
    Returns:
    
    -this.
  - asType
```
<T extends Quantity<T>> Quantity<T> asType(java.lang.Class<T> type)
                                    throws java.lang.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);
    
    Type Parameters:
    
    T - The type of the quantity.
    
    Parameters:
    
    type - the quantity class identifying the nature of the quantity.
    
    Returns:
    
    this quantity parameterized with the specified type.
    
    Throws:
    
    java.lang.ClassCastException - if the dimension of this unit is different from the specified quantity dimension.
    
    java.lang.UnsupportedOperationException - if the specified quantity class does not have a SI unit for the quantity.
    
    See Also:
    
    Unit.asType(Class)
  - getValue
```
java.lang.Number getValue()
```
    Returns the value of this Quantity.
    
    Returns:
    
    a value.
  - getUnit
```
Unit<Q> getUnit()
```
    Returns the unit of this Quantity.
    
    Returns:
    
    the unit (shall not be null).
  - toSystemUnit
```
default Quantity<Q> toSystemUnit()
```
    Convenient method equivalent to to(getUnit().toSystemUnit()).
    
    Returns:
    
    this quantity or a new quantity equivalent to this quantity stated in SI units.
    
    Throws:
    
    java.lang.ArithmeticException - if the result is inexact and the quotient has a non-terminating decimal expansion.

Interface Quantity<Q extends Quantity<Q>>

Arithmetic operations

Method Summary

Method Detail

add

subtract

divide

divide

multiply

multiply

to

inverse

negate

asType

getValue

getUnit

toSystemUnit