Q
- The type of the quantity.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 = ...
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.
apiNote This interface places no restrictions on the mutability of implementations, however immutability is strongly recommended. All implementations must beComparable
.Unit
,
Wikipedia: Quantity,
Martin Fowler -
QuantityModifier and Type | Interface | Description |
---|---|---|
static class |
Quantity.Scale |
Modifier and Type | Method | Description |
---|---|---|
Quantity<Q> |
add(Quantity<Q> addend) |
Returns the sum of this
Quantity with the one specified. |
<T extends Quantity<T>> |
asType(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(Number divisor) |
Returns the quotient of this
Quantity divided by the Number
specified. |
Quantity<?> |
divide(Quantity<?> divisor) |
Returns the quotient of this
Quantity divided by the Quantity
specified. |
Quantity.Scale |
getScale() |
Returns the
Scale of this Quantity , if it's absolute or relative. |
Unit<Q> |
getUnit() |
Returns the unit of this
Quantity . |
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(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()) . |
Quantity<Q> add(Quantity<Q> addend)
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.addend
- the Quantity
to be added.this + addend
.Quantity<Q> subtract(Quantity<Q> subtrahend)
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.subtrahend
- the Quantity
to be subtracted.this - subtrahend
.Quantity<?> divide(Quantity<?> divisor)
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.divisor
- the Quantity
divisor.this / divisor
.ClassCastException
- if the type of an element in the specified operation is
incompatible with this quantityQuantity<Q> divide(Number divisor)
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.divisor
- the Number
divisor.this / divisor
.Quantity<?> multiply(Quantity<?> multiplicand)
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.multiplicand
- the Quantity
multiplicand.this * multiplicand
.ClassCastException
- if the type of an element in the specified operation is
incompatible with this quantityQuantity<Q> multiply(Number multiplicand)
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.multiplicand
- the Number
multiplicand.this * multiplicand
.Quantity<Q> to(Unit<Q> unit)
Quantity
converted into another (compatible)
Unit
.unit
- the Unit unit
in which the returned quantity is stated.ArithmeticException
- if the result is inexact and the quotient has a non-terminating decimal expansion.Quantity<?> inverse()
Quantity
that is the multiplicative inverse of this
Quantity
, having reciprocal value and reciprocal unit as given by
this.getUnit().inverse()
.Quantity
<T extends Quantity<T>> Quantity<T> asType(Class<T> type) throws ClassCastException
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);
T
- The type of the quantity.type
- the quantity class identifying the nature of the quantity.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.Unit.asType(Class)
Number getValue()
Quantity
.Unit<Q> getUnit()
Quantity
.null
).default Quantity<Q> toSystemUnit()
to(getUnit().toSystemUnit())
.ArithmeticException
- if the result is inexact and the quotient has a non-terminating
decimal expansion.Quantity.Scale getScale()
Scale
of this Quantity
, if it's absolute or relative.Copyright © 2014–2020 Jean-Marie Dautelle, Werner Keil, Otavio Santana. All rights reserved.