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

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

All Implemented Interfaces:
  Comparable<UnitExpr>, Iterable<OneUnit>

    public class UnitExpr

extends Object
implements Iterable<OneUnit>, Comparable<UnitExpr>

A parsed unit expression.

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

Method Summary
`boolean` | `allUnitsRecognised(Syntax syntax)` Indicates whether the parsed expression is composed only of recognised units, in the sense of `OneUnit.isRecognisedUnit(uk.me.nxg.unity.Syntax)`.
`boolean` | `allUnitsRecommended(Syntax syntax)` Indicates whether the parsed expression is composed only of recommended units, in the sense of `OneUnit.isRecommendedUnit(uk.me.nxg.unity.Syntax)`.
`boolean` | `allUsageConstraintsSatisfied(Syntax syntax)` Indicates whether the expression is being used in a way which satisfies any usage constraints, in the sense of `OneUnit.satisfiesUsageConstraints(uk.me.nxg.unity.Syntax)`.
`UnitExpr` | `canonicalize()` Returns a new UnitExpr, representing the same expression, but with the units in some canonical order (not specified here, but consistent within a library release).
`int` | `compareTo(UnitExpr ue)` Provides an ordering for UnitExpr instances.
`boolean` | `equals(Object o)`
`Dimensions` | `getDimensions()` Obtains the dimensions of the complete expression.
`double` | `getFactor()` Obtain the factor multiplying this expression
`double` | `getLogFactor()` Obtain the base-10 log of the factor multiplying this expression
`OneUnit` | `getUnit(int idx)` Get one of the units within the expression, by index.
`OneUnit` | `getUnit(String reqUnit)` Extracts the unit information from the expression, keyed by a symbolic name for the unit, as defined by the syntax which was used to parse the expression.
`OneUnit` | `getUnit(UnitDefinition reqUnit)` Extracts the unit information from the expression, keyed by an abstract unit instance.
`boolean` | `isFullyConformant(Syntax syntax)` Indicates whether the expression is fully conformant with the appropriate recommendations.
`Iterator<OneUnit>` | `iterator()` Return a representation of the parsed expression as an iterator.
`int` | `size()` The number of units in the expression, which will always be at least one
`Iterator<OneUnit>` | `sortedIterator()` Return a representation of the parsed expression as an iterator, with the units in a canonical order.
`String` | `toDebugString()` Format the unit expression as a string, in some sort of canonical/unambiguous form.
`String` | `toString()` Produces a string representation of the unit expression, in a form suitable for display
`String` | `toString(Syntax syntax)` Produces a string representation of the unit expression, in a format appropriate to the given syntax.
`String` | `toString(Syntax syntax, Locale locale)` Produces a string representation of the unit expression, in a format appropriate to the given syntax, and with output respecting the conventions of the given locale.

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

Method Detail

### canonicalize

    public UnitExpr canonicalize()

  Returns a new UnitExpr, representing the same expression, but with the units in some canonical order (not specified here, but consistent within a library release).

### getLogFactor

    public double getLogFactor()

  Obtain the base-10 log of the factor multiplying this expression

### getFactor

    public double getFactor()

  Obtain the factor multiplying this expression

### iterator

    public Iterator<OneUnit> iterator()

  Return a representation of the parsed expression as an iterator.

  Specified by:
    `iterator` in interface `Iterable<OneUnit>`

### sortedIterator

    public Iterator<OneUnit> sortedIterator()

  Return a representation of the parsed expression as an iterator, with the units in a canonical order. The order is not specified here, but it is consistent in any library release.

### getUnit

    public OneUnit getUnit(UnitDefinition reqUnit)

  Extracts the unit information from the expression, keyed by an abstract unit instance. Returns null if the unit is not present in the expression.

  At present, this won't fully work if there is more than one occurrence of a unit in an expression, for example in the case "m^3/mm". It's not clear if that should be disallowed, or if not how it should be manipulated, so this part of the interface will quite possibly change in some way in future.

  Parameters:
    `reqUnit` - a non-null unit definition

### getUnit

    public OneUnit getUnit(String reqUnit)

  Extracts the unit information from the expression, keyed by a symbolic name for the unit, as defined by the syntax which was used to parse the expression. For example, metres are represented by the symbol ‘m’. Returns null if the unit is not present in the expression. If there is more than one symbolic representation for a unit in a given syntax – for example, some syntaxes permit both ‘yr’ and ‘a’ for year – then either may be used to look up the unit in an expression which was parsed using that syntax.

  If the argument is not a recognised unit in the parsing system, then this returns the unit which has a matching symbol. For example, ‘erg’ is not recognised symbol in the CDS syntax, so if the string ‘erg/s’ were parsed using the CDS parser, then the call `getUnit("erg")` would find the (unknown) unit ‘erg’, but using `getUnit(UnitDefinition)` with an ‘Erg’ UnitDefinition would retrieve nothing.

  Parameters:
    `reqUnit` - a non-null string indicating a unit symbol
  Returns:
    a unit, or null if the specified unit is not in the expression

### getUnit

    public OneUnit getUnit(int idx)

  Get one of the units within the expression, by index.

  Parameters:
    `idx` - the unit to retrieve
  See Also:
    `size()`

### size

    public int size()

  The number of units in the expression, which will always be at least one

### allUnitsRecommended

    public boolean allUnitsRecommended(Syntax syntax)

  Indicates whether the parsed expression is composed only of recommended units, in the sense of `OneUnit.isRecommendedUnit(uk.me.nxg.unity.Syntax)`. Recommended units are units which are both recognised and not deprecated.

  Parameters:
    `syntax` - the syntax with respect to which the units should be checked

### allUnitsRecognised

    public boolean allUnitsRecognised(Syntax syntax)

  Indicates whether the parsed expression is composed only of recognised units, in the sense of `OneUnit.isRecognisedUnit(uk.me.nxg.unity.Syntax)`. That is, an expression composed of only non-deprecated and unknown units has no deprecated units.

  Parameters:
    `syntax` - the syntax with respect to which the units should be checked

### allUsageConstraintsSatisfied

    public boolean allUsageConstraintsSatisfied(Syntax syntax)

  Indicates whether the expression is being used in a way which satisfies any usage constraints, in the sense of `OneUnit.satisfiesUsageConstraints(uk.me.nxg.unity.Syntax)`. 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`

### isFullyConformant

    public boolean isFullyConformant(Syntax syntax)

  Indicates whether the expression is fully conformant with the appropriate recommendations. That is, all units are recommended, and are being used in a way which is conformant with any usage constraints.

  Parameters:
    `syntax` - one of the syntaxes of `Syntax`

### getDimensions

    public Dimensions getDimensions()

  Obtains the dimensions of the complete expression. If any of the units within the expression were unrecognised, this returns null.

### compareTo

    public int compareTo(UnitExpr ue)

  Provides an ordering for UnitExpr instances. The order is consistent, but unspecified here.

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

### equals

    public boolean equals(Object o)

  Overrides:
    `equals` in class `Object`

### toString

    public String toString()

  Produces a string representation of the unit expression, in a form suitable for display

  Overrides:
    `toString` in class `Object`

### toString

    public String toString(Syntax syntax)
                    throws UnitParserException

  Produces a string representation of the unit expression, in a format appropriate to the given syntax. The syntaxes are those of `Syntax`. The output is locale-independent (which in practice means it is in the `java.text.Locale.US` locale).

  Parameters:
    `syntax` - the syntax to generate
  Throws:
    `UnitParserException`

### toString

    public String toString(Syntax syntax,
                           Locale locale)
                    throws UnitParserException

  Produces a string representation of the unit expression, in a format appropriate to the given syntax, and with output respecting the conventions of the given locale. The syntaxes are those of `Syntax`. If `locale` is null, the output is locale-independent (which in practice means it is in the `java.text.Locale.US` locale); note that this is distinct from the process's default locale.

  Parameters:
    `syntax` - the syntax to generate
    `locale` - the locale to use, or null to use a ‘no-locale’ locale
  Throws:
    `UnitParserException`

### toDebugString

    public String toDebugString()

  Format the unit expression as a string, in some sort of canonical/unambiguous form. The format of the output is unspecified: the `toString()` method is generally preferred as a way of formatting expressions.

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