Class Unit<U extends Unit<U>>

    • Constructor Detail

      • Unit

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

      • 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.
        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
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • getUnit

        public static SIUnit getUnit​(String unitString)
        Find or create a unit for the given SI dimensions.
        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