Package 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

Modifier and Type
Method
Description
`boolean`
`allUnitsRecognised()`
Indicates whether the parsed expression is composed only units which are recognised in at least one syntax, and including guesses.
`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)`, and excluding guesses.
`boolean`
`allUnitsRecognised(Syntax syntax, boolean includeGuesses)`
Indicates whether the parsed expression is composed only of recognised units, in the sense of `OneUnit.isRecognisedUnit(uk.me.nxg.unity.Syntax)`, plus a test of whether we should or should not include units which were identified via the guessing mechanism.
`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)`
`static UnitExpr`
`getDimensionlessExpression()`
Return a unit expression representing a dimensionless quantity.
`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.
`int`
`hashCode()`
`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, unless the expression represents the dimensionless expression
`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

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

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

## Method Details

### getDimensionlessExpression

public static UnitExpr getDimensionlessExpression()
Return a unit expression representing a dimensionless quantity.

Returns:
  a complete expression

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

Returns:
  a new canonical UnitExpr

### getLogFactor

public double getLogFactor()
Obtain the base-10 log of the factor multiplying this expression

Returns:
  the log of the multiplying factor

### getFactor

public double getFactor()
Obtain the factor multiplying this expression

Returns:
  the multiplying factor

### iterator

public Iterator<OneUnit> iterator()
Return a representation of the parsed expression as an iterator.

Specified by:
  `iterator` in interface `Iterable<OneUnit>`
Returns:
  an iteration of OneUnit instances

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

Returns:
  an iteration of OneUnit instances

### 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
Returns:
  a single OneUnit

### 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 (zero-indexed)
Returns:
  a single unit
Throws:
  `IndexOutOfBoundsException` - if the required unit doesn't exist
See Also:
  - `size()`

### size

public int size()
The number of units in the expression, which will always be at least one, unless the expression represents the dimensionless expression

Returns:
  the number of units in the list

### 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
Returns:
  true if all of the units in the expression are recommended ones

### allUnitsRecognised

public boolean allUnitsRecognised()
Indicates whether the parsed expression is composed only units which are recognised in at least one syntax, and including guesses.

This is equivalent to `allUnitsRecognised(Syntax.ALL, true)`.

Returns:
  true if all of the units in the expression are recognised ones
See Also:
  - `allUnitsRecognised(Syntax,boolean)`

### 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)`, and excluding guesses.

This is equivalent to `allUnitsRecognised(syntax, false)`, so this test will return false if any of the units in the expression, though recognised, were recognised only by guessing.

Parameters:
  `syntax` - the syntax with respect to which the units should be checked
Returns:
  true if all of the units in the expression are recognised ones
See Also:
  - `allUnitsRecognised(Syntax,boolean)`

### allUnitsRecognised

public boolean allUnitsRecognised(Syntax syntax, boolean includeGuesses)
Indicates whether the parsed expression is composed only of recognised units, in the sense of `OneUnit.isRecognisedUnit(uk.me.nxg.unity.Syntax)`, plus a test of whether we should or should not include units which were identified via the guessing mechanism.

Guessed units are recognised in at least one syntax, but not necessarily the syntax specified in the `syntax` argument.

If the `syntax` argument is given as `Syntax.ALL`, then a unit is recognised if it is recognised in any syntax.

Parameters:
  `syntax` - the syntax with respect to which the units should be checked
  `includeGuesses` - if false, then fail the test if any of the recognised units were obtained by guessing
Returns:
  true if all of the units in the expression are recognised ones
See Also:
  - `UnitParser.setGuessing(boolean)`

### 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`
Returns:
  true if all of the units in the expression satisfy their usage constraints

### 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`
Returns:
  true if all of the units in the expression are fully conformant

### getDimensions

public Dimensions getDimensions()
Obtains the dimensions of the complete expression. If any of the units within the expression were unrecognised, this returns null.

Returns:
  the overall dimensions of the expression

### 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>`
Returns:
  an integer

### equals

public boolean equals(Object o)

Overrides:
  `equals` in class `Object`

### hashCode

public int hashCode()

Overrides:
  `hashCode` 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 UnwritableExpression
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
Returns:
  a string representation of the expression
Throws:
  `UnwritableExpression` - if the expression cannot be written in that syntax

### toString

public String toString(Syntax syntax, Locale locale) throws UnwritableExpression
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
Returns:
  a string representation of the expression
Throws:
  `UnwritableExpression` - if the expression cannot be written in that syntax

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

Returns:
  a string representation of the expression