uk.me.nxg.unity
Class FunctionOfUnit

java.lang.Object
  extended by uk.me.nxg.unity.OneUnit
      extended by uk.me.nxg.unity.FunctionOfUnit

public class FunctionOfUnit
extends OneUnit

Represents a function of a unit, such as log(m). This consists of a function ('log' in this case) and an operand ('m' in this case). The interpretation of log(m) is that it represents the log of the dimensionless number obtained by dividing a quantity (which presumably has the dimensions of length) by the quantity 1 m.

The functions getBaseUnitName(), getBaseUnitDefinition(), and getBaseUnitString(), apply to the operand. In particular, they give the information about the first unit in the function operand, even if it has multiple units (such as log(V^2/mm). This isn't ideal, but it's probably roughly what is wanted in the majority of cases where this function is used.

The functions isRecognisedUnit(uk.me.nxg.unity.Syntax) and isRecommendedUnit(uk.me.nxg.unity.Syntax) are true if they would be true when applied to the operand and the function is a recognised in this syntax; there are no usage constraints on functions, so the function satisfiesUsageConstraints(uk.me.nxg.unity.Syntax) is true if it would be true when applied to the operand.


Method Summary
 UnitDefinition getBaseUnitDefinition()
          Returns the known base unit.
 String getBaseUnitName()
          Returns the name of this unit.
 String getBaseUnitString()
          Returns the base unit string, which will only be non-null if this unit was an unrecognised one.
 Dimensions getDimensions()
          Return the dimensions of the unit, if it is a recognised one.
 FunctionDefinition getFunctionDefinition()
          The function which is applied to the operand.
 String getFunctionName()
          The function which is applied to the operand.
 int getPrefix()
          Returns the prefix of the unit, as a base-ten log.
 OneUnit getUnit(UnitDefinition reqUnit)
          Returns the unit in the operand which corresponds to the required unit.
 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.
 String toDebugString()
          Write out the unit in a testable format.
 String toString()
          Format this unit in some sort of canonical form.
 String toString(Syntax syntax)
          Format this unit in some sort of canonical form appropriate to the given syntax.
 String unitString(Syntax syntax)
          Obtains the string representation of the unit, including prefix, in the given syntax.
 
Methods inherited from class uk.me.nxg.unity.OneUnit
getExponent
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getPrefix

public int getPrefix()
Description copied from class: OneUnit
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

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

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.getBaseUnitString() 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

getBaseUnitName

public 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.

Specified by:
getBaseUnitName in class OneUnit

getBaseUnitString

public String getBaseUnitString()
Description copied from class: OneUnit
Returns the base unit string, which will only be non-null if this unit was an unrecognised one. This is non-private because UnitExpr needs to know this when it's searching for units in the expression; it's package-only because this is not how clients should format units -- they should use the UnitExpr formatting facilities instead.

Specified by:
getBaseUnitString in class OneUnit

getUnit

public OneUnit getUnit(UnitDefinition reqUnit)
Returns the unit in the operand which corresponds to the required 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 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).

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

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.

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).

Specified by:
isRecommendedUnit in class OneUnit
Parameters:
syntax - one of the syntaxes of Syntax
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

toDebugString

public 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

toString

public String toString()
Description copied from class: OneUnit
Format this unit in some sort of canonical form. The form is unspecified. This should not generally be used for formatted output -- for that, it will generally be more appropriate to use UnitExpr.toString().

Specified by:
toString in class OneUnit

toString

public String toString(Syntax syntax)
Description copied from class: OneUnit
Format this unit in some sort of canonical form appropriate to the given syntax. The form is unspecified. This should not generally be used for formatted output -- for that, it will generally be more appropriate to use UnitExpr.toString().

Specified by:
toString in class OneUnit

unitString

public String unitString(Syntax syntax)
                  throws UnitParserException
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'.

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

getFunctionDefinition

public FunctionDefinition getFunctionDefinition()
The function which is applied to the operand. If this is not a recognised function in the originating syntax, then this returns null. Either this function or getFunctionName() returns non-null, and not both.


getFunctionName

public String getFunctionName()
The function which is applied to the operand. If this is not a recognised function in the originating syntax, then this returns null. Either this function or getFunctionDefinition() returns non-null, and not both.