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

      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

      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

      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:
    • 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