Interface Quantity<Q extends Quantity<Q>>

All Known Subinterfaces:
Acceleration, Action, AmountOfSubstance, Angle, Area, Dimensionless, ElectricCapacitance, ElectricCharge, ElectricConductance, ElectricConductivity, ElectricCurrent, ElectricPermittivity, ElectricPotential, ElectricResistance, Energy, Entropy, Force, Frequency, Inductance, Length, LuminousIntensity, MagneticFlux, MagneticFluxDensity, MagneticPermeability, Mass, MassDensity, Power, Pressure, SpecificHeatCapacity, Temperature, ThermalConductivity, Time, Velocity, Volume, VolumetricFlowRate, WaveNumber
All Known Implementing Classes:
Money
public interface Quantity<Q extends Quantity<Q>>
A physical quantity combining a numerical value with a unit of measurement.

This interface provides type-safe dimensional analysis using parameterized types. Quantities are immutable - all operations return new instances.

Example Usage:

Since:
1.0
Author:
Silvere Martin-Michiellot, Gemini AI (Google DeepMind)

  • Method Details

    • getValue

      Real getValue()
      Returns the numerical value of this quantity in its current unit.
      Returns:
      the quantity value

    • getUnit

      Unit<Q> getUnit()
      Returns the unit of measurement for this quantity.
      Returns:
      the unit

    • to

      Quantity<Q> to(Unit<Q> targetUnit)
      Converts this quantity to the specified unit.

      Returns a new quantity with the same physical magnitude but expressed in the target unit.

      Parameters:
      targetUnit - the unit to convert to
      Returns:
      a new quantity in the target unit
      Throws:
      IllegalArgumentException - if units are incompatible

    • getValue

      default Real getValue(Unit<Q> unit)
      Returns the value of this quantity in the specified unit.

      Convenience method equivalent to to(unit).getValue().

      Parameters:
      unit - the unit to convert to
      Returns:
      the value in the specified unit

    • add

      Quantity<Q> add(Quantity<Q> other)
      Adds another quantity to this one.

      If the units differ, the other quantity is converted to this quantity's unit before addition.

      Parameters:
      other - the quantity to add
      Returns:
      a new quantity representing the sum

    • subtract

      Quantity<Q> subtract(Quantity<Q> other)
      Subtracts another quantity from this one.

      If the units differ, the other quantity is converted to this quantity's unit before subtraction.

      Parameters:
      other - the quantity to subtract
      Returns:
      a new quantity representing the difference

    • multiply

      Quantity<Q> multiply(Real scalar)
      Multiplies this quantity by a scalar value.
      Parameters:
      scalar - the scalar multiplier
      Returns:
      a new quantity scaled by the given factor

    • multiply

      default Quantity<Q> multiply(double scalar)
      Multiplies this quantity by a scalar value.
      Parameters:
      scalar - the scalar multiplier
      Returns:
      a new quantity scaled by the given factor

    • multiply

      <R extends Quantity<R>> Quantity<?> multiply(Quantity<R> other)
      Multiplies this quantity by another quantity.

      The result's unit is the product of the two units. For example, multiplying Length by Length gives Area.

      Type Parameters:
      R - the other quantity type
      Parameters:
      other - the quantity to multiply by
      Returns:
      a new quantity representing the product

    • divide

      Quantity<Q> divide(Real scalar)
      Divides this quantity by a scalar value.
      Parameters:
      scalar - the scalar divisor
      Returns:
      a new quantity divided by the given factor

    • divide

      default Quantity<Q> divide(double scalar)
      Divides this quantity by a scalar value.
      Parameters:
      scalar - the scalar divisor
      Returns:
      a new quantity divided by the given factor

    • divide

      <R extends Quantity<R>> Quantity<?> divide(Quantity<R> other)
      Divides this quantity by another quantity.

      The result's unit is the quotient of the two units. For example, dividing Length by Time gives Velocity.

      Type Parameters:
      R - the other quantity type
      Parameters:
      other - the quantity to divide by
      Returns:
      a new quantity representing the quotient

    • abs

      Quantity<Q> abs()
      Returns the absolute value of this quantity.
      Returns:
      a new quantity with absolute value

    • negate

      Quantity<Q> negate()
      Returns the negation of this quantity.
      Returns:
      a new quantity with negated value

    • asType

      default <R extends Quantity<R>> Quantity<R> asType(Class<R> type)
      Casts this quantity to the specified type.

      This is an unchecked cast that allows reinterpreting the quantity type. Use with caution - the caller must ensure dimensional consistency.

      Type Parameters:
      R - the target quantity type
      Parameters:
      type - the target quantity class
      Returns:
      this quantity cast to the specified type

    • isZero

      default boolean isZero()
      Checks if this quantity is zero within tolerance.
      Returns:
      true if the value is approximately zero

    • compareTo

      int compareTo(Quantity<Q> other)
      Compares this quantity with another for order. Both quantities are compared in this quantity's unit.
      Parameters:
      other - the quantity to compare with
      Returns:
      negative if less, zero if equal, positive if greater

    • isGreaterThan

      default boolean isGreaterThan(Quantity<Q> other)
      Checks if this quantity is strictly greater than another quantity.
      Parameters:
      other - the quantity to compare with
      Returns:
      true if this > other

    • isLessThan

      default boolean isLessThan(Quantity<Q> other)
      Checks if this quantity is strictly less than another quantity.
      Parameters:
      other - the quantity to compare with
      Returns:
      true if this invalid input: '<' other

    • isGreaterThanOrEqualTo

      default boolean isGreaterThanOrEqualTo(Quantity<Q> other)
      Checks if this quantity is greater than or equal to another quantity.
      Parameters:
      other - the quantity to compare with
      Returns:
      true if this >= other

    • isLessThanOrEqualTo

      default boolean isLessThanOrEqualTo(Quantity<Q> other)
      Checks if this quantity is less than or equal to another quantity.
      Parameters:
      other - the quantity to compare with
      Returns:
      true if this invalid input: '<'= other

    • equals

      boolean equals(Quantity<Q> other, Real tolerance)
      Checks if this quantity equals another within tolerance.
      Parameters:
      other - the quantity to compare with
      tolerance - the acceptable difference
      Returns:
      true if quantities are equal within tolerance

    • pow

      Quantity<?> pow(int exponent)
      Returns this quantity raised to the specified exponent.
      Parameters:
      exponent - the exponent
      Returns:
      this quantity raised to the exponent

    • sqrt

      Quantity<?> sqrt()
      Returns the square root of this quantity.
      Returns:
      the square root of this quantity