Class UnitExpr
- java.lang.Object
-
- uk.me.nxg.unity.UnitExpr
-
public class UnitExpr extends java.lang.Object implements java.lang.Iterable<OneUnit>, java.lang.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
All Methods Static Methods Instance Methods Concrete Methods 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 ofOneUnit.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 ofOneUnit.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 ofOneUnit.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 ofOneUnit.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(java.lang.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 expressiondouble
getLogFactor()
Obtain the base-10 log of the factor multiplying this expressionOneUnit
getUnit(int idx)
Get one of the units within the expression, by index.OneUnit
getUnit(java.lang.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.java.util.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 expressionjava.util.Iterator<OneUnit>
sortedIterator()
Return a representation of the parsed expression as an iterator, with the units in a canonical order.java.lang.String
toDebugString()
Format the unit expression as a string, in some sort of canonical/unambiguous form.java.lang.String
toString()
Produces a string representation of the unit expression, in a form suitable for displayjava.lang.String
toString(Syntax syntax)
Produces a string representation of the unit expression, in a format appropriate to the given syntax.java.lang.String
toString(Syntax syntax, java.util.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.
-
-
-
Method Detail
-
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 java.util.Iterator<OneUnit> iterator()
Return a representation of the parsed expression as an iterator.- Specified by:
iterator
in interfacejava.lang.Iterable<OneUnit>
- Returns:
- an iteration of OneUnit instances
-
sortedIterator
public java.util.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(java.lang.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 usinggetUnit(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:
java.lang.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 ofOneUnit.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 ofOneUnit.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 ofOneUnit.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 asSyntax.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 checkedincludeGuesses
- 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 ofOneUnit.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 ofSyntax
- 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 ofSyntax
- 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 interfacejava.lang.Comparable<UnitExpr>
- Returns:
- an integer
-
equals
public boolean equals(java.lang.Object o)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
toString
public java.lang.String toString()
Produces a string representation of the unit expression, in a form suitable for display- Overrides:
toString
in classjava.lang.Object
-
toString
public java.lang.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 ofSyntax
. The output is locale-independent (which in practice means it is in thejava.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 java.lang.String toString(Syntax syntax, java.util.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 ofSyntax
. Iflocale
is null, the output is locale-independent (which in practice means it is in thejava.text.Locale.US
locale); note that this is distinct from the process's default locale.- Parameters:
syntax
- the syntax to generatelocale
- 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 java.lang.String toDebugString()
Format the unit expression as a string, in some sort of canonical/unambiguous form. The format of the output is unspecified: thetoString()
method is generally preferred as a way of formatting expressions.- Returns:
- a string representation of the expression
-
-