Package org.djunits.unit.si

Class SIUnit

java.lang.Object
org.djunits.unit.si.SIUnit
All Implemented Interfaces:
UnitInterface<SIUnit,SIQuantity>
public class SIUnit extends Object implements UnitInterface<SIUnit,SIQuantity>
SIUnit stores the dimensionality of a unit using the SI standards. Angle (rad) and solid angle (sr) have been added to be able to specify often used units regarding rotation.

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

Author:
Alexander Verbraeck

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final SIUnit
    DIMLESS
    the dimensionless SIUnit.
    static final int
    NUMBER_DIMENSIONS
    The (currently) 9 dimensions we take into account: rad, sr, kg, m, s, A, K, mol, cd.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SIUnit(int[] dimensions)
    Create an immutable SIUnit instance based on a safe copy of a given dimensions specification.
    SIUnit(int angle, int solidAngle, int mass, int length, int time, int current, int temperature, int amountOfSubstance, int luminousIntensity)
    Create an immutable SIUnit instance based on a safe copy of a given dimensions specification.

  • Method Summary

    Modifier and Type
    Method
    Description
    static SIUnit
    add(SIUnit dim1, SIUnit dim2)
    Add two SIUnit and return the new SIUnit.
    boolean
    equals(Object obj)
     
    SIUnit
    getBaseUnit()
    Return the base unit for this unit.
    String
    getDisplayAbbreviation()
    Retrieve the display abbreviation, and apply localization when possible.
    String
    getId()
    Return the id, which is the main abbreviation, of the unit.
    String
    getName()
    Return the name, which is the main written explanation, of the unit.
    Scale
    getScale()
    Retrieve the scale of this unit.
    SIPrefix
    getSiPrefix()
    Return the SI-prefix so it can be localized if necessary.
    String
    getStoredDisplayAbbreviation()
    Retrieve the stored display abbreviation, without localization.
    String
    getStoredName()
    Return the name, which is the main written explanation, of the unit.
    String
    getStoredTextualAbbreviation()
    Retrieve the stored textual abbreviation, which doubles as the id of the unit.
    String
    getTextualAbbreviation()
    Retrieve the textual abbreviation, which doubles as the id of the unit.
    UnitSystem
    getUnitSystem()
    Retrieve the unit system of this unit.
    int
    hashCode()
     
    SIUnit
    invert()
    Invert a set of SI dimensions; instead of m/s we get s/m.
    SIUnit
    minus(SIUnit other)
    Subtract a set of SI dimensions from this SIUnit.
    static SIUnit
    of(String siString)
    Parse a string representing SI dimensions to an SIUnit object.
    SIQuantity
    ofSi(double si)
    Return an SI-quantity for this unit with a value.
    SIUnit
    plus(SIUnit other)
    Add a set of SI dimensions to this SIUnit.
    SIUnit
    pow(int n)
    Raise a set of SI dimensions to the n-th power.
    SIUnit
    setSiPrefix(String prefix)
    Set the SI-prefix so it can be localized if necessary.
    SIUnit
    setSiPrefix(SIPrefix siPrefix)
    Set the SI-prefix so it can be localized if necessary.
    SIUnit
    setSiPrefixKilo(String prefix)
    Set the SI-prefix so it can be localized if necessary.
    SIUnit
    setSiPrefixPer(String prefix)
    Set the SI-prefix so it can be localized if necessary.
    String[]
    siAbbreviations()
    Returns a safe copy of the SI abbreviations (a public static final String[] is mutable).
    int[]
    siDimensions()
    Return a safe copy of the exponents of the SI dimensions in the order rad, sr, kg, m, s, A, K, mol, cd.
    SIUnit
    siUnit()
    Return the SI unit for this unit.
    static SIUnit
    subtract(SIUnit dim1, SIUnit dim2)
    Subtract an SIUnit (dim2) from another SIUnit (dim1) and return the new SIUnit.
    String
    toHTMLString(boolean divided, boolean separator)
    Return a string such as "kgm/s2" or or "kg.m.s-2" from this SIUnit.
    String
    toString()
     
    String
    toString(boolean divided, boolean separator)
    Return a string such as "kgm/s2" or "kg.m/s2" or "kg.m.s-2" from this SIUnit.
    String
    toString(boolean divided, boolean separator, boolean power)
    Return a string such as "kgm/s2" or "kg.m/s^2" or "kg.m.s^-2" from this SIUnit.
    String
    toString(boolean divided, String separator, String powerPrefix, String powerPostfix)
    Return a string such as "kgm/s2" or "kg.m/s^2" or "kg.m.s^-2" from this SIUnit.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.djunits.unit.UnitInterface

    fromBaseValue, quantityInUnit, toBaseValue

  • Field Details

    • NUMBER_DIMENSIONS

      public static final int NUMBER_DIMENSIONS
      The (currently) 9 dimensions we take into account: rad, sr, kg, m, s, A, K, mol, cd.
      See Also:

    • DIMLESS

      public static final SIUnit DIMLESS
      the dimensionless SIUnit.

  • Constructor Details

    • SIUnit

      public SIUnit(int[] dimensions)
      Create an immutable SIUnit instance based on a safe copy of a given dimensions specification. As an example, speed is indicated as length = 1; time = -1 with the other dimensions equal to zero.
      Parameters:
      dimensions - The (currently) 9 dimensions of the SI unit we distinguish: 0: angle (rad), 1: solid angle (sr), 2: mass (kg), 3: length (m), 4: time (s), 5: current (A), 6: temperature (K), 7: amount of substance (mol), 8: luminous intensity (cd).

    • SIUnit

      public SIUnit(int angle, int solidAngle, int mass, int length, int time, int current, int temperature, int amountOfSubstance, int luminousIntensity)
      Create an immutable SIUnit instance based on a safe copy of a given dimensions specification.
      Parameters:
      angle - dimension of the angle (rad)
      solidAngle - dimension of the solidAngle (sr)
      mass - dimension of the mass (kg)
      length - dimension of the length (m)
      time - dimension of the time (s)
      current - dimension of the current (A)
      temperature - dimension of the temperature (K)
      amountOfSubstance - dimension of the amount of substance (mol)
      luminousIntensity - dimension of the luminous intensity (cd)

  • Method Details

    • of

      public static SIUnit of(String siString) throws UnitRuntimeException
      Parse a string representing SI dimensions to an SIUnit object. Example: SIUnit.of("kgm/s2") and SIUnit.of("kgms-2") will both be translated to a dimensions object with vector {0,0,1,1,-2,0,0,0,0}. It is allowed to use 0 or 1 for the dimensions. Having the same unit in the numerator and the denominator is not seen as a problem: the values are subtracted from each other, so m/m will have a length dimensionality of 0. Dimensions between -9 and 9 are allowed. Spaces, periods and ^ are taken out, but other characters are not allowed and will lead to a UnitException. The order of allowed units is arbitrary, so "kg/ms2" is accepted as well as "kg/s^2.m".
      Parameters:
      siString - the string to parse
      Returns:
      the corresponding SI dimensions
      Throws:
      UnitRuntimeException - when the string could not be parsed into dimensions

    • siAbbreviations

      public String[] siAbbreviations()
      Returns a safe copy of the SI abbreviations (a public static final String[] is mutable).
      Returns:
      a safe copy of the SI abbreviations

    • siDimensions

      public int[] siDimensions()
      Return a safe copy of the exponents of the SI dimensions in the order rad, sr, kg, m, s, A, K, mol, cd. Since it is a safe copy, calculations can be carried out on the int[] return value.
      Returns:
      a safe copy of the exponents of the SI dimensions in the order rad, sr, kg, m, s, A, K, mol, cd

    • plus

      public SIUnit plus(SIUnit other)
      Add a set of SI dimensions to this SIUnit. Note: as dimensions are considered to be immutable, a new dimension is returned. The original dimension (this) remains unaltered.
      Parameters:
      other - the dimensions to add (usually as a result of multiplication of scalars)
      Returns:
      the new dimensions with the dimensions of this object plus the dimensions in the parameter

    • minus

      public SIUnit minus(SIUnit other)
      Subtract a set of SI dimensions from this SIUnit. Note: as dimensions are considered to be immutable, a new dimension is returned. The original dimension (this) remains unaltered.
      Parameters:
      other - the dimensions to subtract (usually as a result of division of scalars)
      Returns:
      the new dimensions with the dimensions of this object minus the dimensions in the parameter

    • invert

      public SIUnit invert()
      Invert a set of SI dimensions; instead of m/s we get s/m. Note: as dimensions are considered to be immutable, a new dimension is returned. The original dimension (this) remains unaltered.
      Returns:
      the new dimensions that are the inverse of the dimensions in this object

    • pow

      public SIUnit pow(int n)
      Raise a set of SI dimensions to the n-th power. Note: as dimensions are considered to be immutable, a new dimension is returned. The original dimension (this) remains unaltered.
      Parameters:
      n - the power to which to raise this set of dimensions
      Returns:
      the new dimensions with the dimensions of this object raised to the n-th power

    • add

      public static SIUnit add(SIUnit dim1, SIUnit dim2)
      Add two SIUnit and return the new SIUnit. Usually, dimensions are added as a result of multiplication of scalars.
      Parameters:
      dim1 - the first set of dimensions
      dim2 - the second set of dimensions
      Returns:
      the new dimensions with the sum of the dimensions in the parameters

    • subtract

      public static SIUnit subtract(SIUnit dim1, SIUnit dim2)
      Subtract an SIUnit (dim2) from another SIUnit (dim1) and return the new SIUnit. Usually, dimensions are added as a result of division of scalars.
      Parameters:
      dim1 - the first set of dimensions
      dim2 - the second set of dimensions that will be subtracted from dim1
      Returns:
      the new dimensions with the difference of the dimensions in the parameters

    • ofSi

      public SIQuantity ofSi(double si)
      Description copied from interface: UnitInterface
      Return an SI-quantity for this unit with a value.
      Specified by:
      ofSi in interface UnitInterface<SIUnit,SIQuantity>
      Parameters:
      si - the value in SI or BASE units
      Returns:
      an SI-quantity for this unit with the given si-value

    • toString

      public String toString(boolean divided, String separator, String powerPrefix, String powerPostfix)
      Return a string such as "kgm/s2" or "kg.m/s^2" or "kg.m.s^-2" from this SIUnit.
      Parameters:
      divided - if true, return m/s2 for acceleration; if false return ms-2
      separator - add this string between successive units, e.g. kg.m.s-2 instead of kgms-2
      powerPrefix - the prefix for the power, e.g., "^" or "<sup>"
      powerPostfix - the postfix for the power, e.g., "</sup>"
      Returns:
      a formatted string for this SIUnit

    • toString

      public String toString(boolean divided, boolean separator)
      Return a string such as "kgm/s2" or "kg.m/s2" or "kg.m.s-2" from this SIUnit.
      Parameters:
      divided - if true, return m/s2 for acceleration; if false return ms-2
      separator - if true, add a period between successive units, e.g. kg.m.s-2 instead of kgms-2
      Returns:
      a formatted string describing this SIUnit

    • toString

      public String toString(boolean divided, boolean separator, boolean power)
      Return a string such as "kgm/s2" or "kg.m/s^2" or "kg.m.s^-2" from this SIUnit.
      Parameters:
      divided - if true, return m/s2 for acceleration; if false return ms-2
      separator - if true, add a period between successive units, e.g. kg.m.s-2 instead of kgms-2
      power - if true, add a ^ sign before the power, e.g., "kg.m^2/s^3" instead of "kg.m2/s3"
      Returns:
      a formatted string describing this SIUnit

    • toHTMLString

      public String toHTMLString(boolean divided, boolean separator)
      Return a string such as "kgm/s2" or or "kg.m.s-2" from this SIUnit.
      Parameters:
      divided - if true, return "m/s2" for acceleration; if false return "ms-2"
      separator - if true, add a period between successive units, e.g. kg.m.s-2
      Returns:
      a formatted string describing this SIUnit

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getId

      public String getId()
      Description copied from interface: UnitInterface
      Return the id, which is the main abbreviation, of the unit.
      Specified by:
      getId in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the id (main abbreviation) of the unit

    • getScale

      public Scale getScale()
      Description copied from interface: UnitInterface
      Retrieve the scale of this unit.
      Specified by:
      getScale in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the scale of this unit

    • getUnitSystem

      public UnitSystem getUnitSystem()
      Description copied from interface: UnitInterface
      Retrieve the unit system of this unit.
      Specified by:
      getUnitSystem in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      unitSystem the unit system of this unit

    • siUnit

      public SIUnit siUnit()
      Description copied from interface: UnitInterface
      Return the SI unit for this unit.
      Specified by:
      siUnit in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the SI unit for this unit

    • getBaseUnit

      public SIUnit getBaseUnit()
      Description copied from interface: UnitInterface
      Return the base unit for this unit.
      Specified by:
      getBaseUnit in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the base unit for this unit

    • getTextualAbbreviation

      public String getTextualAbbreviation()
      Description copied from interface: UnitInterface
      Retrieve the textual abbreviation, which doubles as the id of the unit. Apply localization when possible.
      Specified by:
      getTextualAbbreviation in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the (localized) textual abbreviation

    • getDisplayAbbreviation

      public String getDisplayAbbreviation()
      Description copied from interface: UnitInterface
      Retrieve the display abbreviation, and apply localization when possible.
      Specified by:
      getDisplayAbbreviation in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the (localized) display abbreviation

    • getName

      public String getName()
      Description copied from interface: UnitInterface
      Return the name, which is the main written explanation, of the unit. Apply localization when possible.
      Specified by:
      getName in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the (localized) name of the unit

    • getStoredTextualAbbreviation

      public String getStoredTextualAbbreviation()
      Description copied from interface: UnitInterface
      Retrieve the stored textual abbreviation, which doubles as the id of the unit. Do not apply localization.
      Specified by:
      getStoredTextualAbbreviation in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the stored (non-localized) textual abbreviation

    • getStoredDisplayAbbreviation

      public String getStoredDisplayAbbreviation()
      Description copied from interface: UnitInterface
      Retrieve the stored display abbreviation, without localization.
      Specified by:
      getStoredDisplayAbbreviation in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the stored (non-localized) display abbreviation

    • getStoredName

      public String getStoredName()
      Description copied from interface: UnitInterface
      Return the name, which is the main written explanation, of the unit. Do not apply localization.
      Specified by:
      getStoredName in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the stored (non-localized) name of the unit

    • setSiPrefix

      public SIUnit setSiPrefix(SIPrefix siPrefix)
      Description copied from interface: UnitInterface
      Set the SI-prefix so it can be localized if necessary.
      Specified by:
      setSiPrefix in interface UnitInterface<SIUnit,SIQuantity>
      Parameters:
      siPrefix - the SI-prefix to set
      Returns:
      the unit for method chaining

    • setSiPrefix

      public SIUnit setSiPrefix(String prefix)
      Description copied from interface: UnitInterface
      Set the SI-prefix so it can be localized if necessary. This method does NOT handle kilo-prefixes.
      Specified by:
      setSiPrefix in interface UnitInterface<SIUnit,SIQuantity>
      Parameters:
      prefix - the string-representation of the SI-prefix to set
      Returns:
      the unit for method chaining

    • setSiPrefixKilo

      public SIUnit setSiPrefixKilo(String prefix)
      Description copied from interface: UnitInterface
      Set the SI-prefix so it can be localized if necessary. This method handles kilo-prefixes.
      Specified by:
      setSiPrefixKilo in interface UnitInterface<SIUnit,SIQuantity>
      Parameters:
      prefix - the string-representation of the SI-prefix to set
      Returns:
      the unit for method chaining

    • setSiPrefixPer

      public SIUnit setSiPrefixPer(String prefix)
      Description copied from interface: UnitInterface
      Set the SI-prefix so it can be localized if necessary. This method handles per-unit prefixes.
      Specified by:
      setSiPrefixPer in interface UnitInterface<SIUnit,SIQuantity>
      Parameters:
      prefix - the string-representation of the SI-prefix to set
      Returns:
      the unit for method chaining

    • getSiPrefix

      public SIPrefix getSiPrefix()
      Description copied from interface: UnitInterface
      Return the SI-prefix so it can be localized if necessary.
      Specified by:
      getSiPrefix in interface UnitInterface<SIUnit,SIQuantity>
      Returns:
      the SI-prefix of this unit, or null when the unit has no SI-prefix

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

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