Package uk.me.nxg.unity

Class SimpleUnit

  • All Implemented Interfaces:
    java.lang.Comparable<OneUnit>
    Direct Known Subclasses:
    SimpleBinaryUnit, SimpleDecimalUnit
    public abstract class SimpleUnit
extends OneUnit
    A single simple unit, such as 'kg'. This is represented as a prefix, a base unit and an exponent. For example, the string "mm s^-2" will result in two SimpleUnit instances, one of which will have a base unit of "m" and a prefix power of -3, and the other of which will have a base unit of "s" and an exponent of -2.

    This represents the abstract unit, shorn of the symbols which were parsed to obtain it. Thus if, in some odd syntax, the symbol 'x' were used to denote metres, then the SimpleUnit instance which resulted would be the same as the OneUnit which resulted from a more conventional syntax.

    Also, there is a potential ambiguity if a symbol is recognised in one syntax, but not in another. Thus if the string 'erg' were parsed in a syntax which didn't recognise that, then it would be stored as just that, an unrecognised symbol, not associated with the UnitDefinition for the erg. Similarly, if a unit is parsed with guessing, then we may encounter a unit which is recognised in the sense of OneUnit.isRecognisedUnit(), but not in the sense of OneUnit.isRecognisedUnit(Syntax).

    The class's instances are immutable.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(OneUnit o)  
      boolean equals​(java.lang.Object o)
      Two units are equal if they have the same power, units and exponent.
      UnitDefinition getBaseUnitDefinition()
      Returns the known base unit.
      java.lang.String getBaseUnitName()
      Returns the name of this unit.
      java.lang.String getBaseUnitString()  
      Dimensions getDimensions()
      Return the dimensions of the unit, if it is a recognised one.
      java.lang.String getOriginalUnitString()
      Obtains the representation of the unit, as it originally appeared in the parsed input.
      int getPrefix()
      Returns the prefix of the unit, as a base-ten log.
      int hashCode()  
      boolean isRecognisedUnit()
      Indicates whether the base unit is one of those recognised in any syntax.
      boolean isRecognisedUnit​(Syntax syntax)
      Indicates whether the base unit is one of those recognised within the specification of the given syntax.
      boolean isRecommendedUnit​(Syntax syntax)
      Indicates whether the base unit is one of those recommended within the specification of the given syntax.
      boolean satisfiesUsageConstraints​(Syntax syntax)
      Indicates whether the unit is being used in a way which satisfies any usage constraints.
      java.lang.String toDebugString()
      Write out the unit in a testable format.
      java.lang.String toString()
      Format this unit in readable form.
      java.lang.String toString​(Syntax syntax)
      Format this unit in readable form, appropriate to the given syntax.
      java.lang.String unitString()
      Obtains the string form of the unit, including prefix, with a default syntax.
      java.lang.String unitString​(Syntax syntax)
      Obtains the string representation of the unit, including prefix, in the given syntax.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • getPrefix

        public int getPrefix()
        Returns the prefix of the unit, as a base-ten log. Thus a prefix of "m", for "milli", would produce a prefix of -3.
        Specified by:
        getPrefix in class OneUnit
        Returns:
        the power of ten which multiplies the unit

      • toString

        public java.lang.String toString()
        Description copied from class: OneUnit
        Format this unit in readable form. The form is unspecified.

        This should not generally be used for formatted output – for that, it will more often be better to use UnitExpr.toString().

        Specified by:
        toString in class OneUnit
        Returns:
        a string representation of the unit

      • toString

        public java.lang.String toString​(Syntax syntax)
                          throws UnwritableExpression
        Description copied from class: OneUnit
        Format this unit in readable form, appropriate to the given syntax. The form is unspecified.

        This should not generally be used for formatted output – for that, it will more often be better to use UnitExpr.toString().

        Specified by:
        toString in class OneUnit
        Parameters:
        syntax - one of the known syntaxes
        Returns:
        a string representation of the unit
        Throws:
        UnwritableExpression - if the unit can't be written in the given syntax

      • unitString

        public java.lang.String unitString​(Syntax syntax)
                            throws UnwritableExpression
        Description copied from class: OneUnit
        Obtains the string representation of the unit, including prefix, in the given syntax. That is, return ‘mm’ not ‘m’ or ‘metre’. If a unit has more than one representation in a given syntax, then this will produced the ‘preferred one’.

        This will fail, with a UnitParserException, in the rare cases where the unit string is inexpressible in the given syntax: for example the CDS syntax permits only the log function to be applied to a unit, and will fail if it is asked to display a different function.

        Specified by:
        unitString in class OneUnit
        Parameters:
        syntax - one of the syntaxes of Syntax
        Returns:
        a non-null string representation of the unit
        Throws:
        UnwritableExpression - if the unit string is inexpressible in the given syntax

      • getBaseUnitDefinition

        public UnitDefinition getBaseUnitDefinition()
        Description copied from class: OneUnit
        Returns the known base unit. If the unit wasn't recognised as a known unit in the syntax in which the string was parsed, then this returns null, though OneUnit.getBaseUnitName() will not.

        Note that the ‘base unit’ is simply the unit without the prefix, and doesn't refer to the fundamental SI base units. Thus in the expression "MW", it is ‘W’, Watt, that is the base unit.

        Specified by:
        getBaseUnitDefinition in class OneUnit
        Returns:
        a base unit

      • getBaseUnitName

        public java.lang.String getBaseUnitName()
        Description copied from class: OneUnit
        Returns the name of this unit. If the unit is a known one, then this will return a name for the unit such as ‘Metre’, or ‘Julian year’; if it is not, then this can do no more than return the unit symbol.

        This should be used for identification or similar purposes. To write out the unit you should generally use UnitExpr.toString().

        Specified by:
        getBaseUnitName in class OneUnit
        Returns:
        the string name of this unit

      • getBaseUnitString

        public java.lang.String getBaseUnitString()

      • getDimensions

        public Dimensions getDimensions()
        Description copied from class: OneUnit
        Return the dimensions of the unit, if it is a recognised one. If this isn't a recognised unit, return null.
        Specified by:
        getDimensions in class OneUnit
        Returns:
        the dimensions of the unit, or null if these aren't avaiable

      • getOriginalUnitString

        public java.lang.String getOriginalUnitString()
        Description copied from class: OneUnit
        Obtains the representation of the unit, as it originally appeared in the parsed input. This will differ from what is produced by unitString if (a) the original was a dispreferred representation of a recognised unit (for example ‘yr’ vs ‘a’), or (b) if the unit was (successfully) guessed from an otherwise unrecognised string.
        Specified by:
        getOriginalUnitString in class OneUnit
        Returns:
        the original input representation of the unit

      • unitString

        public java.lang.String unitString()
        Obtains the string form of the unit, including prefix, with a default syntax. That is, return 'mm' not 'm'.

        The default syntax is (currently) the syntax with which this unit was originally read.

        Returns:
        a string representation of the unit

      • isRecognisedUnit

        public boolean isRecognisedUnit​(Syntax syntax)
        Description copied from class: OneUnit
        Indicates whether the base unit is one of those recognised within the specification of the given syntax. In this context, ‘recognised’ means ‘mentioned in the specification’, so deprecated units count as recognised ones.

        Note that this checks that the unit is a recognised one: we don't (currently) check whether the abbreviation that got us here is a recommended one (for example, ‘pixel’ is a valid FITS/CDS name for pixels, and ‘pix’ is a FITS and OGIP one). This also means that if we guessed a unit, and that unit is a recognised one in this syntax, then this method returns true.

        If the syntax is Syntax.ALL, then this checks whether this is a recognised unit in any syntax.

        Specified by:
        isRecognisedUnit in class OneUnit
        Parameters:
        syntax - one of the syntaxes of Syntax
        Returns:
        true if the unit is recognised
        See Also:
        OneUnit.isRecommendedUnit(uk.me.nxg.unity.Syntax)

      • isRecognisedUnit

        public boolean isRecognisedUnit()
        Description copied from class: OneUnit
        Indicates whether the base unit is one of those recognised in any syntax.

        This is equivalent to isRecognisedUnit(Syntax.ALL). If this method returns true, then OneUnit.getBaseUnitDefinition() would return non-null, and vice versa if this method returns false.

        Specified by:
        isRecognisedUnit in class OneUnit
        Returns:
        true if the unit is recognised

      • isRecommendedUnit

        public boolean isRecommendedUnit​(Syntax syntax)
        Description copied from class: OneUnit
        Indicates whether the base unit is one of those recommended within the specification of the given syntax. In this context, ‘recommended’ means ‘mentioned in the specification’ and not deprecated. Thus all ‘recommended’ units are also a fortiori ‘recognised’.

        Note that this checks that the unit is a recommended one: we don't (currently) check whether the abbreviation that got us here is a recommended one (for example, "pixel" is a valid FITS/CDS name for pixels, and "pix" is a FITS and OGIP one). This also means that if we guessed a unit, and that unit is a recommended one in this syntax, then this method returns true.

        Specified by:
        isRecommendedUnit in class OneUnit
        Parameters:
        syntax - one of the syntaxes of Syntax
        Returns:
        true if the unit is a recommended one
        See Also:
        OneUnit.isRecognisedUnit(uk.me.nxg.unity.Syntax)

      • satisfiesUsageConstraints

        public boolean satisfiesUsageConstraints​(Syntax syntax)
        Description copied from class: OneUnit
        Indicates whether the unit is being used in a way which satisfies any usage constraints. Principally, this tests whether a unit which may not be used with SI prefixes was provided with a prefix, but there may be other constraints present.

        An unrecognised unit has no constraints, and so will always satisfy them; this extends to units which are unrecognised in a particular syntax.

        Specified by:
        satisfiesUsageConstraints in class OneUnit
        Parameters:
        syntax - one of the syntaxes of Syntax
        Returns:
        true if the unit satisfies its usage constraints

      • toDebugString

        public java.lang.String toDebugString()
        Description copied from class: OneUnit
        Write out the unit in a testable format. This is for debugging and testing.
        Specified by:
        toDebugString in class OneUnit
        Returns:
        a string representation of the unit

      • equals

        public boolean equals​(java.lang.Object o)
        Two units are equal if they have the same power, units and exponent. They don't have to have been obtained from the same syntax, so that in a syntax which (for example) permitted both "yr" and "a" for years, two SimpleUnit instances, obtained from parsing the two alternatives, would be regarded as equal.
        Overrides:
        equals in class java.lang.Object

      • compareTo

        public int compareTo​(OneUnit o)
        Specified by:
        compareTo in interface java.lang.Comparable<OneUnit>
        Specified by:
        compareTo in class OneUnit

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object