Class OneUnit

  • All Implemented Interfaces:
    java.lang.Comparable<OneUnit>
    Direct Known Subclasses:
    FunctionOfUnit, SimpleUnit

    public abstract class OneUnit
    extends java.lang.Object
    implements java.lang.Comparable<OneUnit>
    A single unit.

    The class's instances are immutable.

    This class has no public constructors. To obtain instances of this class, parse a unit string using a UnitParser.

    A unit can be ‘quoted’, indicating that it is to be parsed as an ‘unknown’ unit even if its name matches that of a ‘known’ unit (for example, 'B' is a unit of ‘B’, and neither byte nor Bel, and the 'furlong' is a ‘furlong’ and not, as it would otherwise be parsed, a femto-urlong). This mechanism is syntactically permitted only in the VOUnits syntax, and is used only for output and validity checks (see isRecognisedUnit(uk.me.nxg.unity.Syntax)), and not for processing. All ‘quoted’ units are classed as not ‘recognised’.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected OneUnit​(float exponent)  
      protected OneUnit​(float exponent, boolean isQuoted)
      OneUnit constructor is protected – it should only be invoked by subclass constructors, and they may be invoked from the OneUnit.Maker class.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract int compareTo​(OneUnit o)  
      static java.util.List<OneUnit> divide​(java.util.List<OneUnit> num, java.lang.Iterable<OneUnit> den)
      Divide one list of units by another
      abstract UnitDefinition getBaseUnitDefinition()
      Returns the known base unit.
      abstract java.lang.String getBaseUnitName()
      Returns the name of this unit.
      abstract Dimensions getDimensions()
      Return the dimensions of the unit, if it is a recognised one.
      float getExponent()
      Obtains the power the unit is raised to.
      abstract java.lang.String getOriginalUnitString()
      Obtains the representation of the unit, as it originally appeared in the parsed input.
      abstract int getPrefix()
      Returns the prefix of the unit, as a base-ten log.
      boolean isQuoted()
      Is this a ‘quoted’ unit?
      abstract boolean isRecognisedUnit()
      Indicates whether the base unit is one of those recognised in any syntax.
      abstract boolean isRecognisedUnit​(Syntax syntax)
      Indicates whether the base unit is one of those recognised within the specification of the given syntax.
      abstract boolean isRecommendedUnit​(Syntax syntax)
      Indicates whether the base unit is one of those recommended within the specification of the given syntax.
      static java.util.List<OneUnit> reciprocate​(java.lang.Iterable<OneUnit> ul)
      Produce the reciprocal of the unit, which is a unit which has the negative of the exponent of this one.
      abstract boolean satisfiesUsageConstraints​(Syntax syntax)
      Indicates whether the unit is being used in a way which satisfies any usage constraints.
      abstract java.lang.String toDebugString()
      Write out the unit in a testable format.
      abstract java.lang.String toString()
      Format this unit in readable form.
      abstract java.lang.String toString​(Syntax syntax)
      Format this unit in readable form, appropriate to the given syntax.
      abstract java.lang.String unitString​(Syntax syntax)
      Obtains the string representation of the unit, including prefix, in the given syntax.
      boolean wasGuessed()
      Return true if this unit was guessed.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • OneUnit

        protected OneUnit​(float exponent,
                          boolean isQuoted)
        OneUnit constructor is protected – it should only be invoked by subclass constructors, and they may be invoked from the OneUnit.Maker class.
        Parameters:
        exponent - the power of the base unit
        isQuoted - true, if this is an explicitly quoted unit (VOUnits syntax only)
      • OneUnit

        protected OneUnit​(float exponent)
    • Method Detail

      • isQuoted

        public boolean isQuoted()
        Is this a ‘quoted’ unit?
        Returns:
        true if this unit is quoted
      • getPrefix

        public abstract 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.
        Returns:
        the power of ten which multiplies the unit
      • getBaseUnitDefinition

        public abstract UnitDefinition getBaseUnitDefinition()
        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 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.

        Returns:
        a base unit
      • getBaseUnitName

        public abstract java.lang.String getBaseUnitName()
        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().

        Returns:
        the string name of this unit
      • getDimensions

        public abstract Dimensions getDimensions()
        Return the dimensions of the unit, if it is a recognised one. If this isn't a recognised unit, return null.
        Returns:
        the dimensions of the unit, or null if these aren't avaiable
      • getExponent

        public float getExponent()
        Obtains the power the unit is raised to. For example, for the unit mm^2, return 2.
        Returns:
        the power the unit is raised to
      • wasGuessed

        public boolean wasGuessed()
        Return true if this unit was guessed. That is, if it was identified heuristically, by using a parser configured with UnitParser.setGuessing(boolean)
        Returns:
        true if the unit was guessed
      • isRecognisedUnit

        public abstract boolean isRecognisedUnit​(Syntax syntax)
        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.

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

        public abstract boolean isRecognisedUnit()
        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 getBaseUnitDefinition() would return non-null, and vice versa if this method returns false.

        Returns:
        true if the unit is recognised
      • isRecommendedUnit

        public abstract boolean isRecommendedUnit​(Syntax syntax)
        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.

        Parameters:
        syntax - one of the syntaxes of Syntax
        Returns:
        true if the unit is a recommended one
        See Also:
        isRecognisedUnit(uk.me.nxg.unity.Syntax)
      • satisfiesUsageConstraints

        public abstract boolean satisfiesUsageConstraints​(Syntax syntax)
        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.

        Parameters:
        syntax - one of the syntaxes of Syntax
        Returns:
        true if the unit satisfies its usage constraints
      • toString

        public abstract java.lang.String toString()
        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().

        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation of the unit
      • toString

        public abstract java.lang.String toString​(Syntax syntax)
                                           throws UnwritableExpression
        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().

        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 abstract java.lang.String unitString​(Syntax syntax)
                                             throws UnwritableExpression
        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.

        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
      • getOriginalUnitString

        public abstract java.lang.String getOriginalUnitString()
        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.
        Returns:
        the original input representation of the unit
      • toDebugString

        public abstract java.lang.String toDebugString()
        Write out the unit in a testable format. This is for debugging and testing.
        Returns:
        a string representation of the unit
      • reciprocate

        public static java.util.List<OneUnit> reciprocate​(java.lang.Iterable<OneUnit> ul)
        Produce the reciprocal of the unit, which is a unit which has the negative of the exponent of this one.
        Parameters:
        ul - the expression to be reciprocated
        Returns:
        a new instance
      • divide

        public static java.util.List<OneUnit> divide​(java.util.List<OneUnit> num,
                                                     java.lang.Iterable<OneUnit> den)
        Divide one list of units by another
        Parameters:
        num - the units in the numerator
        den - the units in the denominator
        Returns:
        a list of units
      • compareTo

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