Package org.djunits.quantity.def

Class Quantity<Q extends Quantity<Q>>

java.lang.Object
java.lang.Number
org.djunits.quantity.def.Quantity<Q>
Type Parameters:
Q - the quantity type
All Implemented Interfaces:
Serializable, Comparable<Q>, Additive<Q>, Scalable<Q>, Value<Q,Q>
Direct Known Subclasses:
AbsorbedDose, Acceleration, AmountOfSubstance, Angle, AngularAcceleration, AngularVelocity, Area, ArealObjectDensity, CatalyticActivity, Density, Dimensionless, Duration, ElectricalCapacitance, ElectricalConductance, ElectricalInductance, ElectricalResistance, ElectricCharge, ElectricCurrent, ElectricPotential, Energy, EquivalentDose, FlowMass, FlowVolume, Force, Frequency, Illuminance, Length, LinearDensity, LinearObjectDensity, LuminousFlux, LuminousIntensity, MagneticFlux, MagneticFluxDensity, Mass, Momentum, Power, Pressure, RadioActivity, SIQuantity, SolidAngle, Speed, TemperatureDifference, Torque, Volume, VolumetricObjectDensity
public abstract class Quantity<Q extends Quantity<Q>> extends Number implements Value<Q,Q>, Comparable<Q>, Additive<Q>, Scalable<Q>
Quantity is an abstract class that stores the basic information about a quantity. A physical quantity can be expressed as a value, which is the combination of a numerical value and a unit of measurement. The type of physical quantity is encoded in the class (Length, Speed, Area, etc.) with its associated (base) unit of measurement, whereas the numerical value is stored in the si field. Additionally, each quantity has a displayUnit that gives the preference for the (scaled) display of the quantity, e.g., in a toString() method.

Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djunits.org. The DJUNITS project is distributed under a three-clause BSD-style license.

Author:
Alexander Verbraeck
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final double
    si
    The si value.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Quantity(double valueInUnit, Unit<?,Q> unit)
    Instantiate a quantity with a value and a display unit.

  • Method Summary

    Modifier and Type
    Method
    Description
    Q
    abs()
    Make the SI-values of this element absolute.
    Q
    add(Q increment)
    Add an element to this element, based on the SI-values.
    <TQ extends Quantity<TQ>>
    TQ
    as(Unit<?,TQ> targetUnit)
    Return the quantity 'as' a known quantity, using a unit to express the result in.
    final int
    compareTo(Q other)
     
    SIQuantity
    divide(Quantity<?> quantity)
    Divide this quantity by another quantity, and return a SIQuantity as the result.
    double
    doubleValue()
     
    boolean
    eq(Q other)
    Test if this Quantity is equal to another Quantity.
    boolean
    eq0()
    Test if this Quantity is equal to 0.0.
    boolean
    equals(Object obj)
     
    float
    floatValue()
     
    String
    format()
    Concise description of this quantity.
    String
    format(QuantityFormat format)
    String representation of this quantity after applying the format.
    String
    format(Unit<?,Q> targetUnit)
    String representation of this quantity, expressed in the specified unit.
    boolean
    ge(Q other)
    Test if this Quantity is greater than or equal to another Quantity.
    boolean
    ge0()
    Test if this Quantity is greater than or equal to 0.0.
    Unit<?,Q>
    getDisplayUnit()
    Retrieve the unit of this Value.
    final double
    getInUnit()
    Retrieve the value in the current display unit.
    final double
    getInUnit(Unit<?,Q> targetUnit)
    Retrieve the value converted into some specified unit.
    String
    getName()
    Return the "pretty" name of the quantity.
    boolean
    gt(Q other)
    Test if this Quantity is greater than another Quantity.
    boolean
    gt0()
    Test if this Quantity is greater than 0.0.
    int
    hashCode()
     
    Q
    instantiate(double valueInUnit, Unit<?,Q> unit)
    Instantiate a quantity with a value and a unit.
    abstract Q
    instantiateSi(double siValue)
    Instantiate a quantity with an SI or base value.
    static <Q extends Quantity<Q>>
    Q
    interpolate(Q zero, Q one, double ratio)
    Interpolate between two quantities.
    int
    intValue()
     
    boolean
    isRelative()
    Indicate whether this is a Relative Value.
    boolean
    le(Q other)
    Test if this Quantity is less than or equal to another Quantity.
    boolean
    le0()
    Test if this Quantity is less than or equal to 0.0.
    long
    longValue()
     
    boolean
    lt(Q other)
    Test if this Quantity is less than another Quantity.
    boolean
    lt0()
    Test if this Quantity is less than 0.0.
    static <Q extends Quantity<Q>>
    Q
    max(Q quantity1, Q... quantities)
    Return the maximum value of one or more quantities.
    static <Q extends Quantity<Q>>
    Q
    mean(Q quantity1, Q... quantities)
    Return the mean of one or more quantities.
    static <Q extends Quantity<Q>>
    Q
    min(Q quantity1, Q... quantities)
    Return the minimum value of one or more quantities.
    SIQuantity
    multiply(Quantity<?> quantity)
    Multiply this quantity with another quantity, and return a SIQuantity as the result.
    boolean
    ne(Q other)
    Test if this Quantity is not equal to another Quantity.
    boolean
    ne0()
    Test if this Quantity is not equal to 0.0.
    Q
    negate()
    Negate this element, based on the SI-values.
    static <Q extends Quantity<Q>>
    Q
    of(double valueInUnit, String unitString, Q example)
    Returns a quantity based on a value and the textual representation of the unit, which can be localized.
    static SIQuantity
    product(Quantity<?> quantity1, Quantity<?>... quantities)
    Return the product of one or more quantities.
    Quantity<?>
    reciprocal()
    Return the reciprocal of this quantity (1/q).
    Q
    scaleBy(double factor)
    Scale the element by a dimensionless factor, based on the SI-values.
    Q
    setDisplayUnit(Unit<?,Q> newUnit)
    Set a new display unit for the value.
    double
    si()
    Return the SI value of the quantity.
    SIUnit
    siUnit()
    Return the SI unit of this quantity.
    Q
    subtract(Q decrement)
    Subtract an element from this element, based on the SI-values.
    static <Q extends Quantity<Q>>
    Q
    sum(Q quantity1, Q... quantities)
    Return the sum of one or more quantities.
    String
    toString()
    Description of this quantity with default formatting.
    static <Q extends Quantity<Q>>
    Q
    valueOf(String text, Q example)
    Returns a quantity for the textual representation of a value with a unit.

    Methods inherited from class java.lang.Number

    byteValue, shortValue

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.djunits.value.Scalable

    divideBy

    Methods inherited from interface org.djunits.value.Value

    isAbsolute, setDisplayUnit

  • Field Details

    • si

      public final double si
      The si value.

  • Constructor Details

    • Quantity

      public Quantity(double valueInUnit, Unit<?,Q> unit)
      Instantiate a quantity with a value and a display unit.
      Parameters:
      valueInUnit - the value expressed in the display unit
      unit - the display unit to use

  • Method Details

    • getDisplayUnit

      public Unit<?,Q> getDisplayUnit()
      Description copied from interface: Value
      Retrieve the unit of this Value.
      Specified by:
      getDisplayUnit in interface Value<Q extends Quantity<Q>,Q extends Quantity<Q>>
      Returns:
      the unit of this Value

    • setDisplayUnit

      public Q setDisplayUnit(Unit<?,Q> newUnit)
      Description copied from interface: Value
      Set a new display unit for the value. Internally, the value will not changed since it is stored in a base unit.
      Specified by:
      setDisplayUnit in interface Value<Q extends Quantity<Q>,Q extends Quantity<Q>>
      Parameters:
      newUnit - the new display unit of this value
      Returns:
      'this' for fluent design

    • getInUnit

      public final double getInUnit()
      Retrieve the value in the current display unit.
      Returns:
      the value in the current display unit

    • getInUnit

      public final double getInUnit(Unit<?,Q> targetUnit)
      Retrieve the value converted into some specified unit.
      Parameters:
      targetUnit - the unit to convert the value into
      Returns:
      the double value of this quantity expressed in the target unit

    • getName

      public String getName()
      Return the "pretty" name of the quantity.
      Returns:
      the "pretty" name of the quantity

    • siUnit

      public SIUnit siUnit()
      Return the SI unit of this quantity.
      Returns:
      the SI unit of this quantity

    • si

      public double si()
      Return the SI value of the quantity.
      Returns:
      the SI value of the quantity

    • instantiateSi

      public abstract Q instantiateSi(double siValue)
      Instantiate a quantity with an SI or base value.
      Parameters:
      siValue - the value expressed in the base (SI) unit
      Returns:
      a quantity with the given SI-value and base (SI) unit

    • instantiate

      public Q instantiate(double valueInUnit, Unit<?,Q> unit)
      Instantiate a quantity with a value and a unit.
      Parameters:
      valueInUnit - the double value, expressed in the unit
      unit - the unit
      Returns:
      a quantity with the given value and display unit

    • doubleValue

      public double doubleValue()
      Specified by:
      doubleValue in class Number

    • intValue

      public int intValue()
      Specified by:
      intValue in class Number

    • longValue

      public long longValue()
      Specified by:
      longValue in class Number

    • floatValue

      public float floatValue()
      Specified by:
      floatValue in class Number

    • lt

      public boolean lt(Q other)
      Test if this Quantity is less than another Quantity.
      Parameters:
      other - the right hand side operand of the comparison
      Returns:
      true if this is less than o; false otherwise

    • le

      public boolean le(Q other)
      Test if this Quantity is less than or equal to another Quantity.
      Parameters:
      other - the right hand side operand of the comparison
      Returns:
      true if this is less than or equal to o; false otherwise

    • gt

      public boolean gt(Q other)
      Test if this Quantity is greater than another Quantity.
      Parameters:
      other - the right hand side operand of the comparison
      Returns:
      true if this is greater than o; false otherwise

    • ge

      public boolean ge(Q other)
      Test if this Quantity is greater than or equal to another Quantity.
      Parameters:
      other - the right hand side operand of the comparison
      Returns:
      true if this is greater than or equal to o; false otherwise

    • eq

      public boolean eq(Q other)
      Test if this Quantity is equal to another Quantity.
      Parameters:
      other - the right hand side operand of the comparison
      Returns:
      true if this is equal to o; false otherwise

    • ne

      public boolean ne(Q other)
      Test if this Quantity is not equal to another Quantity.
      Parameters:
      other - the right hand side operand of the comparison
      Returns:
      true if this is not equal to o; false otherwise

    • lt0

      public boolean lt0()
      Test if this Quantity is less than 0.0.
      Returns:
      true if this is less than 0.0; false if this is not less than 0.0

    • le0

      public boolean le0()
      Test if this Quantity is less than or equal to 0.0.
      Returns:
      true if this is less than or equal to 0.0; false if this is not less than or equal to 0.0

    • gt0

      public boolean gt0()
      Test if this Quantity is greater than 0.0.
      Returns:
      true if this is greater than 0.0; false if this is not greater than 0.0

    • ge0

      public boolean ge0()
      Test if this Quantity is greater than or equal to 0.0.
      Returns:
      true if this is greater than or equal to 0.0; false if this is not greater than or equal to 0.0

    • eq0

      public boolean eq0()
      Test if this Quantity is equal to 0.0.
      Returns:
      true if this is equal to 0.0; false if this is not equal to 0.0

    • ne0

      public boolean ne0()
      Test if this Quantity is not equal to 0.0.
      Returns:
      true if this is not equal to 0.0; false if this is equal to 0.0

    • compareTo

      public final int compareTo(Q other)
      Specified by:
      compareTo in interface Comparable<Q extends Quantity<Q>>

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • valueOf

      public static <Q extends Quantity<Q>> Q valueOf(String text, Q example)
      Returns a quantity for the textual representation of a value with a unit. The String representation that can be parsed is the double value in the unit, followed by a localized or English abbreviation of the unit. Spaces are allowed, but not required, between the value and the unit.
      Type Parameters:
      Q - the quantity type
      Parameters:
      text - the textual representation to parse into the quantity
      example - an example instance to deliver
      Returns:
      the quantity representation of the value with its unit
      Throws:
      IllegalArgumentException - when the text cannot be parsed
      NullPointerException - when the text argument is null

    • of

      public static <Q extends Quantity<Q>> Q of(double valueInUnit, String unitString, Q example)
      Returns a quantity based on a value and the textual representation of the unit, which can be localized.
      Type Parameters:
      Q - the quantity type
      Parameters:
      valueInUnit - the value, expressed in the unit as given by unitString
      unitString - the textual representation of the unit
      example - an example instance to deliver
      Returns:
      the quantity representation of the value in its unit
      Throws:
      IllegalArgumentException - when the unit cannot be parsed or is incorrect
      NullPointerException - when the unitString argument is null

    • toString

      public String toString()
      Description of this quantity with default formatting.
      Overrides:
      toString in class Object
      Returns:
      a String with the value of the quantity, with the unit attached.

    • format

      public String format()
      Concise description of this quantity.
      Specified by:
      format in interface Value<Q extends Quantity<Q>,Q extends Quantity<Q>>
      Returns:
      a String with the value of the quantity, with the unit attached.

    • format

      public String format(QuantityFormat format)
      String representation of this quantity after applying the format.
      Parameters:
      format - the format to apply for the quantity
      Returns:
      a String representation of this quantity, formatted according to the given format

    • format

      public String format(Unit<?,Q> targetUnit)
      String representation of this quantity, expressed in the specified unit.
      Specified by:
      format in interface Value<Q extends Quantity<Q>,Q extends Quantity<Q>>
      Parameters:
      targetUnit - the unit into which the quantity is converted for display
      Returns:
      printable string with the quantity value expressed in the specified unit

    • interpolate

      public static <Q extends Quantity<Q>> Q interpolate(Q zero, Q one, double ratio)
      Interpolate between two quantities. Note that the first quantities does not have to be smaller than the second.
      Type Parameters:
      Q - the quantity type
      Parameters:
      zero - the quantity at a ratio of zero
      one - the quantity at a ratio of one
      ratio - the ratio between 0 and 1, inclusive
      Returns:
      a Quantity at the given ratio between 0 and 1

    • max

      @SafeVarargs public static <Q extends Quantity<Q>> Q max(Q quantity1, Q... quantities)
      Return the maximum value of one or more quantities.
      Type Parameters:
      Q - the quantity type
      Parameters:
      quantity1 - the first quantity
      quantities - the other quantities
      Returns:
      the maximum value of the quantities

    • min

      @SafeVarargs public static <Q extends Quantity<Q>> Q min(Q quantity1, Q... quantities)
      Return the minimum value of one or more quantities.
      Type Parameters:
      Q - the quantity type
      Parameters:
      quantity1 - the first quantity
      quantities - the other quantities
      Returns:
      the minimum value of more than two quantities

    • sum

      @SafeVarargs public static <Q extends Quantity<Q>> Q sum(Q quantity1, Q... quantities)
      Return the sum of one or more quantities.
      Type Parameters:
      Q - the quantity type
      Parameters:
      quantity1 - the first quantity
      quantities - the other quantities
      Returns:
      the sum of the quantities

    • product

      @SafeVarargs public static SIQuantity product(Quantity<?> quantity1, Quantity<?>... quantities)
      Return the product of one or more quantities.
      Parameters:
      quantity1 - the first quantity
      quantities - the other quantities
      Returns:
      the product of the quantities

    • mean

      @SafeVarargs public static <Q extends Quantity<Q>> Q mean(Q quantity1, Q... quantities)
      Return the mean of one or more quantities.
      Type Parameters:
      Q - the quantity type
      Parameters:
      quantity1 - the first quantity
      quantities - the other quantities
      Returns:
      the mean of the quantities

    • add

      public Q add(Q increment)
      Description copied from interface: Additive
      Add an element to this element, based on the SI-values. Note that this can lead to unwanted effects for elements with Offset scales: 10 °C + 5 °C = 288.15 °C and not 15 °C.
      Specified by:
      add in interface Additive<Q extends Quantity<Q>>
      Parameters:
      increment - the element to add to this element
      Returns:
      the sum of the SI-values of this element and the SI-values of the other element

    • subtract

      public Q subtract(Q decrement)
      Description copied from interface: Additive
      Subtract an element from this element, based on the SI-values.
      Specified by:
      subtract in interface Additive<Q extends Quantity<Q>>
      Parameters:
      decrement - the element to subtract from this element
      Returns:
      a new element with the SI-values of this element minus the SI-values of the other element

    • abs

      public Q abs()
      Description copied from interface: Additive
      Make the SI-values of this element absolute. A new element wil be returned. Note that this can lead to unwanted effects for elements with Offset scales. A temperature of -10 degrees Celsius will have its Kelvin temperatures negated.
      Specified by:
      abs in interface Additive<Q extends Quantity<Q>>
      Returns:
      a new element with the absolute value for all of its SI-values

    • negate

      public Q negate()
      Description copied from interface: Additive
      Negate this element, based on the SI-values. Note that this can lead to unwanted effects for elements with Offset scales. A temperature in Celsius that is negated, will have its Kelvin temperatures negated.
      Specified by:
      negate in interface Additive<Q extends Quantity<Q>>
      Returns:
      a new element with all of its SI-values negated

    • scaleBy

      public Q scaleBy(double factor)
      Description copied from interface: Scalable
      Scale the element by a dimensionless factor, based on the SI-values. Note that this can lead to unwanted effects for elements with Offset scales. 2 * 10 °C = 293.15 °C and not 20 °C.
      Specified by:
      scaleBy in interface Scalable<Q extends Quantity<Q>>
      Parameters:
      factor - the dimensionless scale factor
      Returns:
      a new element with all of its SI-values scaled by the dimensionless factor

    • multiply

      public SIQuantity multiply(Quantity<?> quantity)
      Multiply this quantity with another quantity, and return a SIQuantity as the result.
      Parameters:
      quantity - the quantity to multiply with
      Returns:
      the multiplication of this quantity and the given quantity

    • divide

      public SIQuantity divide(Quantity<?> quantity)
      Divide this quantity by another quantity, and return a SIQuantity as the result.
      Parameters:
      quantity - the quantity to divide by
      Returns:
      the division of this quantity and the given quantity

    • reciprocal

      public Quantity<?> reciprocal()
      Return the reciprocal of this quantity (1/q).
      Returns:
      the reciprocal of this quantity, with the correct SI units

    • as

      public <TQ extends Quantity<TQ>> TQ as(Unit<?,TQ> targetUnit) throws IllegalArgumentException
      Return the quantity 'as' a known quantity, using a unit to express the result in. Throw a Runtime exception when the SI units of this quantity and the target quantity do not match.
      Type Parameters:
      TQ - target quantity type
      Parameters:
      targetUnit - the unit to convert the quantity to
      Returns:
      a quantity typed in the target quantity class
      Throws:
      IllegalArgumentException - when the units do not match

    • isRelative

      public boolean isRelative()
      Description copied from interface: Value
      Indicate whether this is a Relative Value.
      Specified by:
      isRelative in interface Value<Q extends Quantity<Q>,Q extends Quantity<Q>>
      Returns:
      whether this is a Relative Value