uk.me.nxg.unity
Class UnitExpr

java.lang.Object
  extended by uk.me.nxg.unity.UnitExpr
All Implemented Interfaces:
Iterable<OneUnit>

public class UnitExpr
extends Object
implements Iterable<OneUnit>

A parsed unit expression.


Method Summary
 boolean allUnitsRecognised(String syntax)
          Indicates whether the parsed expression is composed only of recognised units, in the sense of OneUnit.isRecognisedUnit(java.lang.String).
 boolean allUnitsRecommended(String syntax)
          Indicates whether the parsed expression is composed only of recommended units, in the sense of OneUnit.isRecommendedUnit(java.lang.String).
 boolean allUsageConstraintsSatisfied(String syntax)
          Indicates whether the expression is being used in a way which satisfies any usage constraints, in the sense of OneUnit.satisfiesUsageConstraints(java.lang.String).
 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(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(String 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.
 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(String syntax)
          Produces a string representation of the unit expression, in a format appropriate to the given syntax.
 String toString(String 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
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

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>

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

allUnitsRecommended

public boolean allUnitsRecommended(String syntax)
Indicates whether the parsed expression is composed only of recommended units, in the sense of OneUnit.isRecommendedUnit(java.lang.String). 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(String syntax)
Indicates whether the parsed expression is composed only of recognised units, in the sense of OneUnit.isRecognisedUnit(java.lang.String). 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(String syntax)
Indicates whether the expression is being used in a way which satisfies any usage constraints, in the sense of OneUnit.satisfiesUsageConstraints(java.lang.String). 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 UnitParser

isFullyConformant

public boolean isFullyConformant(String 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 UnitParser

getDimensions

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


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(String syntax)
                throws UnitParserException
Produces a string representation of the unit expression, in a format appropriate to the given syntax. The syntaxes are those of UnitParser. 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(String 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 UnitParser. 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.