public final class Units
extends java.lang.Object
implements java.lang.Cloneable
A typical pattern for dealing with units is to (1) check the dimensions, (2) convert parameters to SI units, and (3) use the parameters, now with consistent (SI) units.
Here is a simple example:
// Ensure frequency units have dimensions of inverse time.
if (!freqUnits.haveDimensionsOf(Units.inv(timeUnits))) {
// handle error
}
// Convert both frequency and time to SI units.
freq = freqUnits.toSI(freq);
time = timeUnits.toSI(time);
// Use frequency and time, without worrying about units.
...
When converting many values from some units to some other units
(with the same dimensions) it is more efficient to compute a shift
and scale factor and then use these instead of calling conversion
methods. For example,
// Determine shift and scale.
double shift = toUnits.doubleShiftFrom(fromUnits);
double scale = toUnits.doubleScaleFrom(fromUnits);
// Use shift and scale to convert lots of values.
for (int i=0; i<n; ++i) to[i] = shift+scale*from[i];
Constructor and Description |
---|
Units()
Constructs dimensionless units.
|
Units(java.lang.String definition)
Constructs units from a units definition.
|
Modifier and Type | Method and Description |
---|---|
static Units |
add(Units units,
double s)
Adds a scalar to units.
|
java.lang.Object |
clone()
Clones these units.
|
static boolean |
define(java.lang.String name,
boolean plural,
java.lang.String definition)
Adds a definition of units to the table of units.
|
static Units |
div(Units units,
double s)
Divides units by scalar.
|
static Units |
div(Units units1,
Units units2)
Divides units by units.
|
double |
doubleScaleFrom(Units units)
Returns the scale factor needed to convert values from the specified
units to these units.
|
double |
doubleShiftFrom(Units units)
Returns the shift needed to convert values from the specified
units to these units.
|
boolean |
equals(java.lang.Object object)
Determines whether specified object equals these units.
|
boolean |
equals(Units units)
Determines whether specified units equal these units.
|
float |
floatScaleFrom(Units units)
Returns the scale factor needed to convert values from the specified
units to these units.
|
float |
floatShiftFrom(Units units)
Returns the shift needed to convert values from the specified
units to these units.
|
double |
fromSI(double value)
Converts the specified value in SI base units (seconds, meters, moles,
etc.) to the corresponding value in these units.
|
float |
fromSI(float value)
Converts the specified value in SI base units (seconds, meters, moles,
etc.) to the corresponding value in these units.
|
boolean |
haveDimensions()
Determines whether these units have dimensions.
|
boolean |
haveDimensionsOf(Units units)
Determines whether these units have the dimensions of specified units.
|
static Units |
inv(Units units)
Inverts units.
|
static boolean |
isDefined(java.lang.String name)
Determines whether units with the specified name are defined.
|
static boolean |
isValidDefinition(java.lang.String definition)
Determines if a string is a valid units definition.
|
static Units |
mul(Units units,
double s)
Multiplies units by scalar.
|
static Units |
mul(Units units1,
Units units2)
Multiplies units by units.
|
static Units |
pow(Units units,
int p)
Raises units to a power.
|
java.lang.String |
standardDefinition()
Gets the standard definition of these units.
|
static Units |
sub(Units units,
double s)
Subtracts a scalar from units.
|
double |
toSI(double value)
Converts the specified value in these units to the corresponding value
in SI base units (seconds, meters, moles, etc.).
|
float |
toSI(float value)
Converts the specified value in these units to the corresponding value
in SI base units (seconds, meters, moles, etc.).
|
public Units()
public Units(java.lang.String definition) throws UnitsFormatException
definition
- the units definition (e.g., "coulomb/volt").UnitsFormatException
- if the units definition is not a valid
combination of units already defined.public java.lang.Object clone()
clone
in class java.lang.Object
public boolean equals(java.lang.Object object)
equals
in class java.lang.Object
object
- the object to compare with these units.public boolean equals(Units units)
units
- the units to compare with these units.public float toSI(float value)
value
- the value to convert.public double toSI(double value)
value
- the value to convert.public float fromSI(float value)
value
- the value to convert.public double fromSI(double value)
value
- the value to convert.public float floatShiftFrom(Units units)
units
- the units from which to convert.public double doubleShiftFrom(Units units)
units
- the units from which to convert.public float floatScaleFrom(Units units)
units
- the units from which to convert.public double doubleScaleFrom(Units units)
units
- the units from which to convert.public boolean haveDimensions()
public boolean haveDimensionsOf(Units units)
units
- units with which to compare dimensions.public java.lang.String standardDefinition()
public static Units add(Units units, double s)
units
- first operand.s
- second operand.public static Units sub(Units units, double s)
units
- first operand.s
- second operand.public static Units mul(Units units, double s)
units
- first operand.s
- second operand.public static Units div(Units units, double s)
units
- first operand.s
- second operand.public static Units mul(Units units1, Units units2)
units1
- first operand.units2
- second operand.public static Units div(Units units1, Units units2)
units1
- first operand.units2
- second operand.public static Units inv(Units units)
units
- to invert.public static Units pow(Units units, int p)
units
- first operand.p
- second operand.public static boolean define(java.lang.String name, boolean plural, java.lang.String definition) throws UnitsFormatException
An extensive default table of units may be provided, so that explicit definition using this method may be unnecessary.
Most units are defined in terms of other units already defined. However, some units, such as "ampere" and "second", are base units representing the physical dimensions, such as electric current and time, respectively. We define derived units in terms of base units and other derived units. Only one base units should be defined for each physical dimension.
name
- the string by which the units will be known (e.g,, "farad").plural
- true, if the name has a simple plural form, as in "farads".definition
- the units definition, as in "coulomb/volt". If the
definition is null, then the name is assumed to define new base units,
such as "meter".
Multiplication is denoted by a space, '.', or '*'.
Division is denoted by a '/'.
Addition and subtraction are denoted by '+' and '-'.
Note: only addition and subtraction of constants is
supported, and the constant must appear on the right-hand-side
of the '+' or '-', as in "degK - 273.15", not "-273.15 + degK".
Exponentiation is denoted by '^', as in s^2.UnitsFormatException
- if the definition is not a valid
combination of existing units.public static boolean isValidDefinition(java.lang.String definition)
definition
- the units definition in question (e.g., "coulomb/volt").public static boolean isDefined(java.lang.String name)
name
- the string by which the units are known (e.g., "farad")