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:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Unit.Builder<U extends Unit<U>>	The class that contains the information to build a unit.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
U	build(Unit.Builder<U> builder)	Build the unit, using the information of the provided builder class.
U	clone()
U	deriveLinear(double scaleFactor, String derivedId, String derivedName)	Create a linearly scaled version of this unit.
U	deriveLinear(double scaleFactor, String derivedId, String derivedName, UnitSystem derivedUnitSystem)	Create a linearly scaled version of this unit.
U	deriveLinear(double scaleFactor, String derivedId, String derivedName, UnitSystem derivedUnitSystem, String derivedDefaultDisplayAbbreviation, String derivedDefaultTextualAbbreviation, String... derivedAbbreviations)	Create a linearly scaled version of this unit.
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.
U	deriveSI(SIPrefix siPrefix, double siPrefixPower)	Create a scaled version of this unit with the same unit system but another SI prefix and scale.
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.
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.
boolean	equals(Object obj)
Set<String>	getDefaultAbbreviations()	Retrieve a safe copy of the unit abbreviations.
String	getDefaultDisplayAbbreviation()	Retrieve the default abbreviation.
String	getDefaultTextualAbbreviation()	Retrieve the default textual abbreviation.
String	getId()	Retrieve the unit id.
Set<String>	getLocalizedAbbreviations()	Retrieve a safe copy of the localized unit abbreviations.
String	getLocalizedDisplayAbbreviation()	Retrieve the localized display abbreviation.
String	getLocalizedTextualAbbreviation()	Retrieve the localized textual abbreviation.
String	getName()	Retrieve the name of this unit.
Quantity<U>	getQuantity()	Retrieve the unit base of this unit.
Scale	getScale()	Retrieve the scale of this unit.
U	getStandardUnit()	Retrieve the standard unit (SI Unit) belonging to this unit.
static SIUnit	getUnit(String unitString)	Find or create a unit for the given SI dimensions.
UnitSystem	getUnitSystem()	Retrieve the unit system of this unit.
int	hashCode()
boolean	isBaseSIUnit()	Indicate whether this unit has the standard SI signature.
boolean	isGenerated()	Indicate whether is unit was automatically generated.
static SIUnit	lookupOrCreateUnitWithSIDimensions(SIDimensions siDimensions)	Create or lookup a unit based on given SI dimensions.
Unit.Builder<U>	makeBuilder()	Create a Builder.
String	toString()

Methods inherited from class java.lang.Object

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

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