OneUnit (The Unity library)
Date: 2014-05-13

Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## uk.me.nxg.unity
Class OneUnit

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

All Implemented Interfaces:
  Comparable<OneUnit>

Direct Known Subclasses:
  FunctionOfUnit, SimpleUnit

    public abstract class OneUnit

extends Object
implements 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’.

Method Summary
`abstract int` | `compareTo(OneUnit o)`
`abstract UnitDefinition` | `getBaseUnitDefinition()` Returns the known base unit.
`abstract String` | `getBaseUnitName()` Returns the name of this unit.
`abstract String` | `getBaseUnitString()` Returns the base unit string, which will only be non-null if this unit was an unrecognised one.
`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 int` | `getPrefix()` Returns the prefix of the unit, as a base-ten log.
`boolean` | `isQuoted()` Is this a ‘quoted’ unit?
`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.
`abstract boolean` | `satisfiesUsageConstraints(Syntax syntax)` Indicates whether the unit is being used in a way which satisfies any usage constraints.
`abstract String` | `toDebugString()` Write out the unit in a testable format.
`abstract String` | `toString()` Format this unit in some sort of canonical form.
`abstract String` | `toString(Syntax syntax)` Format this unit in some sort of canonical form appropriate to the given syntax.
`abstract String` | `unitString(Syntax syntax)` Obtains the string representation of the unit, including prefix, in the given syntax.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Method Detail

### isQuoted

    public boolean isQuoted()

  Is this a ‘quoted’ unit?

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

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

### getBaseUnitName

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

### getBaseUnitString

    public abstract String getBaseUnitString()

  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.

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

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

  Parameters:
    `syntax` - one of the syntaxes of `Syntax`
  See Also:
    `isRecommendedUnit(uk.me.nxg.unity.Syntax)`

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

  Parameters:
    `syntax` - one of the syntaxes of `Syntax`
  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`

### toString

    public abstract String toString()

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

  Overrides:
    `toString` in class `Object`

### toString

    public abstract String toString(Syntax syntax)

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

### unitString

    public abstract String unitString(Syntax syntax)
                               throws UnitParserException

  Obtains the string representation of the unit, including prefix, in the given syntax. That is, return ‘mm’ not ‘m’ or ‘metre’.

  Parameters:
    `syntax` - one of the syntaxes of `Syntax`
  Returns:
    a non-null string representation of the unit
  Throws:
    `UnitParserException` - if the syntax is unrecognised

### toDebugString

    public abstract String toDebugString()

  Write out the unit in a testable format. This is for debugging and testing.

### compareTo

    public abstract int compareTo(OneUnit o)

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

Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD