Package org.djunits.unit

Class Unit<U extends Unit<U>>

java.lang.Object
org.djunits.unit.Unit<U>
Type Parameters:
U - the unit to reference the actual unit in return values
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
AbsoluteLinearUnit, AbsorbedDoseUnit, AccelerationUnit, AmountOfSubstanceUnit, AngleUnit, AngularAccelerationUnit, AngularVelocityUnit, AreaUnit, CatalyticActivityUnit, DensityUnit, DimensionlessUnit, DurationUnit, ElectricalCapacitanceUnit, ElectricalChargeUnit, ElectricalConductanceUnit, ElectricalCurrentUnit, ElectricalInductanceUnit, ElectricalPotentialUnit, ElectricalResistanceUnit, EnergyUnit, EquivalentDoseUnit, FlowMassUnit, FlowVolumeUnit, ForceUnit, FrequencyUnit, IlluminanceUnit, LengthUnit, LinearDensityUnit, LuminousFluxUnit, LuminousIntensityUnit, MagneticFluxDensityUnit, MagneticFluxUnit, MassUnit, MomentumUnit, PowerUnit, PressureUnit, RadioActivityUnit, SIUnit, SolidAngleUnit, SpeedUnit, TemperatureUnit, TorqueUnit, VolumeUnit
public class Unit<U extends Unit<U>> extends Object implements Serializable, Cloneable
All units are internally stored relative to a standard unit with conversion factor. This means that e.g., a meter is stored with conversion factor 1.0, whereas kilometer is stored with a conversion factor 1000.0. This means that if we want to express a length meter in kilometers, we have to divide by the conversion factor.

Copyright (c) 2019-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See DJUNITS License

Author:
Alexander Verbraeck
See Also:

  • Constructor Details

    • Unit

      protected Unit()
      Initialize a blank unit that can be built through reflection with several 'setter' methods followed by calling the build(...) method.

  • Method Details

    • build

      public U build(Unit.Builder<U> builder) throws UnitRuntimeException
      Build the unit, using the information of the provided builder class. First check rigorously if all necessary fields in the builder have been set, and whether they are consistent and valid. The behavior is as follows: the defaultAbbreviation and defaultTextualAbbreviation are added to the abbreviations set, if they are not yet already there. When the defaultAbbreviation is set and the defaultTextualAbbreviation is not set, the defaultTextualAbbreviation gets the value of defaultAbbreviation. The reverse also holds: When the defaultTextualAbbreviation is set and the defaultAbbreviation is not set, the defaultAbbreviation gets the value of defaultTextualAbbreviation. When neither the defaultTextualAbbreviation, nor the defaultAbbreviation are set, both get the value of the unitId provided in the builder.

      Note that the unit's name and id can be blank, as long as the SI units show that the unit is dimensionless, and the scale is the IdentityScale.

      Parameters:
      builder - Builder<U>; Builder<U> the object that contains the information about the construction of the class
      Returns:
      U; the constructed unit
      Throws:
      UnitRuntimeException - when not all fields have been set

    • deriveSI

      public U deriveSI(SIPrefix siPrefix, double siPrefixPower, boolean automaticallyGenerated)
      Create a scaled version of this unit with the same unit system but another SI prefix and scale.
      Parameters:
      siPrefix - SIPrefix; the prefix for which to scale the unit
      siPrefixPower - double; the power factor of the SI prefixes, e.g. 2.0 for square meters and 3.0 for cubic meters.
      automaticallyGenerated - boolean; indicate whether the unit has been automatically generated
      Returns:
      U; a scaled instance of this unit
      Throws:
      UnitRuntimeException - when cloning fails

    • deriveSI

      public U deriveSI(SIPrefix siPrefix, double siPrefixPower)
      Create a scaled version of this unit with the same unit system but another SI prefix and scale. This method is used for a unit that is explicitly scaled with an SI prefix.
      Parameters:
      siPrefix - SIPrefix; the prefix for which to scale the unit
      siPrefixPower - double; the power factor of the SI prefixes, e.g. 2.0 for square meters and 3.0 for cubic meters.
      Returns:
      a scaled instance of this unit
      Throws:
      UnitRuntimeException - when cloning fails

    • deriveSIKilo

      public U deriveSIKilo(SIPrefix siPrefix, double siPrefixPower, boolean automaticallyGenerated)
      Create a scaled version of this unit with the same unit system but another SI prefix and scale, where the "k" and "kilo" abbreviations at the start will be replaced by the new information from the SIPrefix.
      Parameters:
      siPrefix - SIPrefix; the prefix for which to scale the unit
      siPrefixPower - double; the power factor of the SI prefixes, e.g. 2.0 for square meters and 3.0 for cubic meters.
      automaticallyGenerated - boolean; indicate whether the unit has been automatically generated
      Returns:
      U; a scaled instance of this unit
      Throws:
      UnitRuntimeException - when cloning fails

    • derivePerSI

      public U derivePerSI(SIPrefix siPrefix, double siPrefixPower, boolean automaticallyGenerated)
      Create a scaled version of this unit with the same unit system but another SI prefix and scale. The "per" units scale in the opposite direction as the normally scaled units. It will yield units like "/ms", "/mus", "/ns", etc.
      Parameters:
      siPrefix - SIPrefix; the prefix for which to scale the unit
      siPrefixPower - double; the power factor of the SI prefixes, e.g. 2.0 for square meters and 3.0 for cubic meters.
      automaticallyGenerated - boolean; indicate whether the unit has been automatically generated
      Returns:
      U; a scaled instance of this unit
      Throws:
      UnitRuntimeException - when cloning fails

    • deriveLinear

      public U deriveLinear(double scaleFactor, String derivedId, String derivedName, UnitSystem derivedUnitSystem, String derivedDefaultDisplayAbbreviation, String derivedDefaultTextualAbbreviation, String... derivedAbbreviations)
      Create a linearly scaled version of this unit. The scale field will be filled with the correct scaleFactor. Note that the unit that is used for derivation can already have a scaleFactor.
      Parameters:
      scaleFactor - double; the linear scale factor of the unit
      derivedId - String; the new id of the derived unit
      derivedName - String; the new name of the derived unit
      derivedUnitSystem - UnitSystem; the unit system of the derived unit
      derivedDefaultDisplayAbbreviation - String; the default abbreviation to use in e.g, the toString() method. Can be null.
      derivedDefaultTextualAbbreviation - String; the default textual abbreviation to use in, e.g, typing. Can be null.
      derivedAbbreviations - String...; the other valid abbreviations for the unit, e.g. {"h", "hr", "hour"}. Can be left out.
      Returns:
      U; a linearly scaled instance of this unit with new id, abbreviation, name, and unit system
      Throws:
      UnitRuntimeException - when cloning fails

    • deriveLinear

      public U deriveLinear(double scaleFactor, String derivedId, String derivedName, UnitSystem derivedUnitSystem)
      Create a linearly scaled version of this unit. The scale field will be filled with the correct scaleFactor. Note that the unit that is used for derivation can already have a scaleFactor.
      Parameters:
      scaleFactor - double; the linear scale factor of the unit
      derivedId - String; the new id of the derived unit
      derivedName - String; the new name of the derived unit
      derivedUnitSystem - UnitSystem; the unit system of the derived unit
      Returns:
      U; a linearly scaled instance of this unit with new id, abbreviation, name, and unit system
      Throws:
      UnitRuntimeException - when cloning fails

    • deriveLinear

      public U deriveLinear(double scaleFactor, String derivedId, String derivedName)
      Create a linearly scaled version of this unit. The unitSystem will be copied. The scale field will be filled with the correct scaleFactor. Note that the unit that is used for derivation can already have a scaleFactor.
      Parameters:
      scaleFactor - double; the linear scale factor of the unit
      derivedId - String; the new id of the derived unit
      derivedName - String; the new name of the derived unit
      Returns:
      U; a linearly scaled instance of this unit with new id, abbreviation, name, and unit system
      Throws:
      UnitRuntimeException - when cloning fails

    • makeBuilder

      public Unit.Builder<U> makeBuilder()
      Create a Builder. Override at subclasses to create extended builder.
      Returns:
      an instance of a builder.

    • lookupOrCreateUnitWithSIDimensions

      public static SIUnit lookupOrCreateUnitWithSIDimensions(SIDimensions siDimensions)
      Create or lookup a unit based on given SI dimensions. E.g., a unit with dimensions 1/s^2 or kg.m/s^2.
      Parameters:
      siDimensions - SIDimensions; the vector with the dimensionality of the unit
      Returns:
      SIUnit; an SIUnit object with the right dimensions

    • getId

      public String getId()
      Retrieve the unit id.
      Returns:
      String; the unit id

    • getDefaultAbbreviations

      public Set<String> getDefaultAbbreviations()
      Retrieve a safe copy of the unit abbreviations.
      Returns:
      Set<String>; the unit abbreviations

    • getDefaultDisplayAbbreviation

      public String getDefaultDisplayAbbreviation()
      Retrieve the default abbreviation.
      Returns:
      String; the default abbreviation

    • getDefaultTextualAbbreviation

      public String getDefaultTextualAbbreviation()
      Retrieve the default textual abbreviation.
      Returns:
      String; the default textual abbreviation

    • getName

      public String getName()
      Retrieve the name of this unit.
      Returns:
      String; the name of this unit

    • getLocalizedAbbreviations

      public Set<String> getLocalizedAbbreviations()
      Retrieve a safe copy of the localized unit abbreviations.
      Returns:
      Set<String>; the localized unit abbreviations

    • getLocalizedDisplayAbbreviation

      public String getLocalizedDisplayAbbreviation()
      Retrieve the localized display abbreviation.
      Returns:
      String; the localized display abbreviation

    • getLocalizedTextualAbbreviation

      public String getLocalizedTextualAbbreviation()
      Retrieve the localized textual abbreviation.
      Returns:
      String; the localized textual abbreviation

    • getScale

      public Scale getScale()
      Retrieve the scale of this unit.
      Returns:
      Scale; the scale of this unit

    • getUnitSystem

      public UnitSystem getUnitSystem()
      Retrieve the unit system of this unit.
      Returns:
      unitSystem the unit system of this unit

    • getQuantity

      public Quantity<U> getQuantity()
      Retrieve the unit base of this unit.
      Returns:
      BaseUnit<U>; the unit base of this unit. if this unit is itself a unit base; the returned value is null

    • isGenerated

      public boolean isGenerated()
      Indicate whether is unit was automatically generated.
      Returns:
      boolean; true if this unit has been automatically generate; false if it was not automatically generated

    • isBaseSIUnit

      public boolean isBaseSIUnit()
      Indicate whether this unit has the standard SI signature.
      Returns:
      boolean; true if this unit has the standard SI signature; false if this unit does not have the standard SI signature

    • getStandardUnit

      public U getStandardUnit()
      Retrieve the standard unit (SI Unit) belonging to this unit.
      Returns:
      U; the standard unit (SI unit) belonging to this unit

    • clone

      public U clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

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

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getUnit

      public static SIUnit getUnit(String unitString)
      Find or create a unit for the given SI dimensions. Note that unitString may be empty, corresponding to a Dimensionless unit.
      Parameters:
      unitString - String; the textual representation of the unit
      Returns:
      SIUnit; the unit
      Throws:
      IllegalArgumentException - when the unit cannot be parsed or is incorrect
      NullPointerException - when the unitString argument is null