Interface Quantity<Q extends Quantity<Q>>
 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>>
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
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 counterintuitive 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
.
 Since:
 1.0
 Version:
 2.3, September 28, 2020
 Author:
 JeanMarie Dautelle, Martin Desruisseaux, Werner Keil, Otavio Santana
 See Also:
Unit
, Wikipedia: Quantity, Martin Fowler  Quantity

Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
Quantity.Scale

Method Summary
Modifier and Type Method Description Quantity<Q>
add(Quantity<Q> addend)
Returns the sum of thisQuantity
with the one specified.<T extends Quantity<T>>
Quantity<T>asType(Class<T> type)
Casts this quantity to a parameterized unit of specified nature or throw aClassCastException
if the dimension of the specified quantity and this measure unit's dimension do not match.Quantity<Q>
divide(Number divisor)
Returns the quotient of thisQuantity
divided by theNumber
specified.Quantity<?>
divide(Quantity<?> divisor)
Returns the quotient of thisQuantity
divided by theQuantity
specified.Quantity.Scale
getScale()
Returns theScale
of thisQuantity
, if it's absolute or relative.Unit<Q>
getUnit()
Returns the unit of thisQuantity
.Number
getValue()
Returns the value of thisQuantity
.Quantity<?>
inverse()
Returns aQuantity
that is the multiplicative inverse of thisQuantity
, having reciprocal value and reciprocal unit as given bythis.getUnit().inverse()
.boolean
isEquivalentTo(Quantity<Q> that)
Compares two instances ofQuantity <Q>
, doing the conversion of unit if necessary.Quantity<Q>
multiply(Number multiplicand)
Returns the product of thisQuantity
with theNumber
value specified.Quantity<?>
multiply(Quantity<?> multiplicand)
Returns the product of thisQuantity
with the one specified.Quantity<Q>
negate()
Returns aQuantity
whose value is(this.getValue())
.Quantity<Q>
subtract(Quantity<Q> subtrahend)
Returns the difference between thisQuantity
and the one specified.Quantity<Q>
to(Unit<Q> unit)
Returns thisQuantity
converted into another (compatible)Unit
.default Quantity<Q>
toSystemUnit()
Convenient method equivalent toto(getUnit().toSystemUnit())
.

Method Details

add
Returns the sum of thisQuantity
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
 theQuantity
to be added. Returns:
this + addend
.

subtract
Returns the difference between thisQuantity
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
 theQuantity
to be subtracted. Returns:
this  subtrahend
.

divide
Returns the quotient of thisQuantity
divided by theQuantity
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
 theQuantity
divisor. Returns:
this / divisor
. Throws:
ClassCastException
 if the type of an element in the specified operation is incompatible with this quantity

divide
Returns the quotient of thisQuantity
divided by theNumber
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
 theNumber
divisor. Returns:
this / divisor
.

multiply
Returns the product of thisQuantity
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
 theQuantity
multiplicand. Returns:
this * multiplicand
. Throws:
ClassCastException
 if the type of an element in the specified operation is incompatible with this quantity

multiply
Returns the product of thisQuantity
with theNumber
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
 theNumber
multiplicand. Returns:
this * multiplicand
.

to
Returns thisQuantity
converted into another (compatible)Unit
. Parameters:
unit
 theUnit unit
in which the returned quantity is stated. Returns:
 this quantity or a new quantity equivalent to this quantity stated in the specified unit.
 Throws:
ArithmeticException
 if the result is inexact and the quotient has a nonterminating decimal expansion.

inverse
Returns aQuantity
that is the multiplicative inverse of thisQuantity
, having reciprocal value and reciprocal unit as given bythis.getUnit().inverse()
. Returns:
 reciprocal
Quantity
 See Also:
 Wikipedia: Multiplicative inverse

negate
Returns aQuantity
whose value is(this.getValue())
. Returns:
this
.

asType
Casts this quantity to a parameterized unit of specified nature or throw aClassCastException
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);
orQuantity<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:
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)

getValue
Returns the value of thisQuantity
. Returns:
 a value.

getUnit
Returns the unit of thisQuantity
. Returns:
 the unit (shall not be
null
).

toSystemUnit
Convenient method equivalent toto(getUnit().toSystemUnit())
. Returns:
 this quantity or a new quantity equivalent to this quantity stated in SI units.
 Throws:
ArithmeticException
 if the result is inexact and the quotient has a nonterminating decimal expansion.

getScale
Returns theScale
of thisQuantity
, if it's absolute or relative. Returns:
 the scale, if it's an absolute or relative quantity.
 Since:
 2.0
 See Also:
 Wikipedia: Absolute scale

isEquivalentTo
Compares two instances ofQuantity <Q>
, doing the conversion of unit if necessary. Parameters:
that
 thequantity<Q>
to be compared with this instance. Returns:
true
ifthat ≡ this
. Throws:
NullPointerException
 if the quantity is null Since:
 2.1
 See Also:
 Cambridge Dictionary: equivalent, LEXICO: equivalent
