SimpleUnit (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 SimpleUnit

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

All Implemented Interfaces:
  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.

The class's instances are immutable.

Method Summary
`int` | `compareTo(OneUnit o)`
`boolean` | `equals(Object o)` Two units are equal if they have the same power, units and exponent.
`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.
`int` | `getPrefix()` Returns the prefix of the unit, as a base-ten log.
`int` | `hashCode()`
`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()` Obtains the string form of the unit, including prefix, with a default 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, isQuoted`

Methods inherited from class java.lang.Object
`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`

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

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

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

### unitString

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

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

  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`

### equals

    public boolean equals(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 `Object`

### compareTo

    public int compareTo(OneUnit o)

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

### hashCode

    public int hashCode()

  Overrides:
    `hashCode` in class `Object`

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