Package uk.me.nxg.unity

# Class FunctionOfUnit

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

All Implemented Interfaces:
  `Comparable<OneUnit>`

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

Modifier and Type
Method
Description
`int`
`compareTo(OneUnit o)`
`boolean`
`equals(Object o)`
`UnitDefinition`
`getBaseUnitDefinition()`
Returns the known base unit.
`String`
`getBaseUnitName()`
Returns the name of this unit.
`String`
`getBaseUnitString()`
`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.
`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.
`OneUnit`
`getUnit(UnitDefinition reqUnit)`
Returns the unit in the operand which corresponds to the required unit.
`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.
`String`
`toDebugString()`
Write out the unit in a testable format.
`String`
`toString()`
Format this unit in readable form.
`String`
`toString(Syntax syntax)`
Format this unit in readable 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

`divide, getExponent, isQuoted, reciprocate, wasGuessed`

### Methods inherited from class java.lang.Object

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

## Method Details

### 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`
Returns:
  the power of ten which multiplies the unit

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

### getUnit

public OneUnit getUnit(UnitDefinition reqUnit)
Returns the unit in the operand which corresponds to the required unit.

Parameters:
  `reqUnit` - a unit representing the one we are to extract
Returns:
  a 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 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

### toString

public 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 String toString(Syntax syntax)
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

### unitString

public 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

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

Returns:
  a function definition

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

Returns:
  a string naming the function

### getOriginalUnitString

public 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

### compareTo

public int compareTo(OneUnit o)

Specified by:
  `compareTo` in interface `Comparable<OneUnit>`
Specified by:
  `compareTo` in class `OneUnit`

### equals

public boolean equals(Object o)

Overrides:
  `equals` in class `Object`

### hashCode

public int hashCode()

Overrides:
  `hashCode` in class `Object`