public interface IQuantity extends IItem, IDisplayable, Comparable<IQuantity>
AUTO, EXACT, VERBOSE
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()
|
Number |
numberValueIn(IUnit targetUnit)
|
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. |
displayUsing
compareTo
KindOfQuantity<?> getType()
IUnit getUnit()
IQuantity in(IUnit targetUnit)
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.targetUnit
IllegalArgumentException
- if targetUnit
is not of the same kind of quantitydoubleValueIn(IUnit)
,
numberValueIn(IUnit)
,
clampedLongValueIn(IUnit)
,
ratioTo(IQuantity)
long longValueIn(IUnit targetUnit, long maxAbsValue) throws QuantityConversionException
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.long
QuantityConversionException
- if the result would be out of rangeIllegalArgumentException
- if targetUnit
is not of the same kind of quantitynumberValueIn(IUnit)
long longValueIn(IUnit targetUnit) throws QuantityConversionException
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)
.
long
QuantityConversionException
- if the result would be out of rangeIllegalArgumentException
- if targetUnit
is not of the same kind of quantitynumberValueIn(IUnit)
long clampedLongValueIn(IUnit targetUnit)
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.
long
IllegalArgumentException
- if targetUnit
is not of the same kind of quantitynumberValueIn(IUnit)
long clampedFloorIn(IUnit targetUnit)
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.long
IllegalArgumentException
- if targetUnit
is not of the same kind of quantityint clampedIntFloorIn(IUnit targetUnit)
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.int
IllegalArgumentException
- if targetUnit
is not of the same kind of quantitydouble doubleValueIn(IUnit targetUnit)
targetUnit
, as a double
. Note that as a result of this conversion, precision
may be lost.double
IllegalArgumentException
- if targetUnit
is not of the same kind of quantityNumber numberValueIn(IUnit targetUnit)
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.Long
if exact, otherwise as some other
Number
IllegalArgumentException
- if targetUnit
is not of the same kind of quantityclampedLongValueIn(IUnit)
long longValue()
long
. This may cause
truncation and loss of precision.long
double doubleValue()
double
. This may cause loss of
precision.double
Number numberValue()
Long
or a
Number
with at least the precision of double
.String persistableString()
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.String interactiveFormat()
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.boolean isLinear()
IQuantity add(IQuantity addend) throws IllegalArgumentException
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.
addend
IllegalArgumentException
- if addend
is not of a compatible kind of quantityIQuantity subtract(IQuantity subtrahend) throws IllegalArgumentException
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.
subtrahend
IllegalArgumentException
- if subtrahend
is not of a compatible kind of quantityIQuantity multiply(long factor) throws UnsupportedOperationException
factor
, if this is a
linear quantity. Otherwise, this operation is undefined and
UnsupportedOperationException
will be thrown.factor
UnsupportedOperationException
- if this quantity is not linearIQuantity multiply(double factor) throws UnsupportedOperationException
factor
, if this is a
linear quantity. Otherwise, this operation is undefined and
UnsupportedOperationException
will be thrown.factor
UnsupportedOperationException
- if this quantity is not lineardouble ratioTo(IQuantity consequent) throws UnsupportedOperationException, IllegalArgumentException
consequent
quantity, if both are of
the same linear kind. Otherwise, this operation is undefined and an exception is thrown.consequent
, as a double
fractionUnsupportedOperationException
- if this quantity is not linearIllegalArgumentException
- if consequent
is not of a compatible kind of quantityCopyright © 2020. All rights reserved.