ucar.units.Unit Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of udunits Show documentation
Show all versions of udunits Show documentation
The ucar.units Java package is for decoding and encoding formatted unit specifications (e.g. "m/s"), converting numeric values between compatible units (e.g. between "m/s" and "knot"), and for performing arithmetic operations on units (e.g. dividing one unit by another, or raising a unit to a power).
The newest version!
/*
* Copyright (c) 1998-2018 University Corporation for Atmospheric Research/Unidata
* See LICENSE for license information.
*/
package ucar.units;
import java.util.Date;
/**
* Interface for units.
*
* @author Steven R. Emmerson
*/
public interface Unit {
/**
* Gets the identifier of this unit.
*
* @return The identifier of this unit. May be null.
*/
public UnitName getUnitName();
/**
* Gets the name of this unit.
*
* @return The name of this unit. May be null.
*/
public String getName();
/**
* Gets the plural form of the name of this unit.
*
* @return The plural of the name of this unit. May be null.
*/
public String getPlural();
/**
* Gets the symbol of this unit.
*
* @return The symbol for this unit. May be null.
*/
public String getSymbol();
/**
* Returns the string representation of the unit.
*
* @return The string representation of the unit
*/
public String toString();
/**
* Returns the canonical string representation of the unit.
*
* @return The canonical string representation.
*/
public String getCanonicalString();
/**
* Returns the derived unit that underlies this unit.
*
* @return The derived unit that underlies this unit.
*/
public DerivedUnit getDerivedUnit();
/**
* Clones this unit, changing the identifier.
*
* @param id
* The identifier for the new unit.
* @return The new unit.
*/
public Unit clone(UnitName id);
/**
* Multiplies this unit by another.
*
* @param that
* The other unit.
* @return The product of multiplying this unit by the other unit.
* @throws MultiplyException
* Can't multiply these units.
*/
public Unit multiplyBy(Unit that) throws MultiplyException;
/**
* Multiplies this unit by a scale factor. For example, if {@code m} is a
* meter unit, then {@code m.multiplyBy(1e-2)} returns a centimeter unit.
*
* @param scale
* The scale factor.
* @return The result of multiplying this unit by the scale factor.
* @throws MultiplyException
* if {@code scale} is zero.
*/
public Unit multiplyBy(double scale) throws MultiplyException;
/**
* Divides this unit by another.
*
* @param that
* The other unit.
* @return The quotient of dividing this unit by the other unit.
* @throws OperationException
* Can't divide these units.
*/
public Unit divideBy(Unit that) throws OperationException;
/**
* Divides this unit into another.
*
* @param that
* The other unit.
* @return The quotient of dividing this unit into the other unit.
* @throws OperationException
* Can't divide these units.
*/
public Unit divideInto(Unit that) throws OperationException;
/**
* Raises this unit to a power.
*
* @param power
* The power.
* @return This result of raising this unit to the power.
* @throws RaiseException
* Can't raise this unit to a power.
*/
public Unit raiseTo(int power) throws RaiseException;
/**
* Returns a unit identical to this instance but whose origin (i.e., zero
* value) has been shifted to the given value. For example, if {@code degK}
* is a Kelvin unit, then {@code degK.shiftTo(273.15)} is a Celsius unit.
*
* @param origin
* The new origin in units of this instance.
* @return A unit convertible with this instance but whose zero value is
* equal to the value {@code origin} of this instance.
* @throws ShiftException
* if the corresponding new unit can't be created.
*/
public Unit shiftTo(double origin) throws ShiftException;
/**
* Returns a unit identical to this instance but whose origin (i.e., zero
* value) has been shifted to the given time. For example, if {@code sec} is
* a second unit, then {@code sec.shiftTo(new Date(0L)} is the unit
* corresponding to seconds since the epoch (1970-01-01 00:00:00 UTC).
*
* @param origin
* The new origin.
* @return A unit whose zero value is the time given by {@code origin}.
* @throws ShiftException
* if the corresponding new unit can't be created. For example,
* if this instance isn't a unit of time.
*/
public Unit shiftTo(Date origin) throws ShiftException;
/**
* Returns a logarithmic unit whose reference level is equal to this unit.
* For example, if {@code mW} is a milliwatt unit, then {@code mW.log(10.)}
* returns a base-ten logarithmic unit with a milliwatt reference level.
*
* @param base
* The logarithmic base. Must be one of {@code 2}, {@link Math#E}
* , or {@code 10}.
* @throws IllegalArgumentException
* if {@code base} isn't one of the allowed values.
*/
public Unit log(double base);
/**
* Gets a Converter that converts numeric values from this unit to another,
* compatible unit.
*
* @param outputUnit
* The unit to which to convert the numerical values.
* @return A converter of numeric values from this unit to the other unit.
* @throws ConversionException
* The units aren't compatible.
*/
public Converter getConverterTo(Unit outputUnit) throws ConversionException;
/**
* Converts a numerical value from this unit to another unit.
*
* @param amount
* The numerical value in this unit.
* @param outputUnit
* The unit to which to convert the numerical value.
* @return The numerical value in the output unit.
* @throws ConversionException
* The units aren't compatible.
*/
public float convertTo(float amount, Unit outputUnit)
throws ConversionException;
/**
* Converts a numerical value from this unit to another unit.
*
* @param amount
* The numerical value in this unit.
* @param outputUnit
* The unit to which to convert the numerical value.
* @return The numerical value in the output unit.
* @throws ConversionException
* The units aren't compatible.
*/
public double convertTo(double amount, Unit outputUnit)
throws ConversionException;
/**
* Converts numerical values from this unit to another unit.
*
* @param amounts
* The numerical values in this unit.
* @param outputUnit
* The unit to which to convert the numerical values.
* @return The numerical values in the output unit. in allocated space.
* @throws ConversionException
* The units aren't compatible.
*/
public float[] convertTo(float[] amounts, Unit outputUnit)
throws ConversionException;
/**
* Converts numerical values from this unit to another unit.
*
* @param amounts
* The numerical values in this unit.
* @param outputUnit
* The unit to which to convert the numerical values.
* @return The numerical values in the output unit. in allocated space.
* @throws ConversionException
* The units aren't compatible.
*/
public double[] convertTo(double[] amounts, Unit outputUnit)
throws ConversionException;
/**
* Converts numerical values from this unit to another unit.
*
* @param input
* The numerical values in this unit.
* @param outputUnit
* The unit to which to convert the numerical values.
* @param output
* The output numerical values. May be the same array as the
* input values.
* @return output.
* @throws ConversionException
* The units aren't compatible.
*/
public float[] convertTo(float[] input, Unit outputUnit, float[] output)
throws ConversionException;
/**
* Converts numerical values from this unit to another unit.
*
* @param input
* The numerical values in this unit.
* @param outputUnit
* The unit to which to convert the numerical values.
* @param output
* The output numerical values. May be the same array as the
* input values.
* @return output.
* @throws ConversionException
* The units aren't compatible.
*/
public double[] convertTo(double[] input, Unit outputUnit, double[] output)
throws ConversionException;
/**
* Indicates if this unit is compatible with another unit.
*
* @param that
* The other unit.
* @return True iff values in this unit are convertible to values in the
* other unit.
*/
public boolean isCompatible(Unit that);
/**
* Indicates if this unit is semantically identical to an object.
*
* @param object
* The object.
* @return true if and only if this unit is semantically
* identical to the object.
*/
public boolean equals(Object object);
/**
* Makes a label for a named quantity.
*
* @param quantityID
* An identifier of the quantity for which the label is intended
* (e.g. "altitude").
* @return A label (e.g. "altitude/km").
*/
public String makeLabel(String quantityID);
/**
* Indicates if values in this unit are dimensionless.
*
* @return true if and only if this unit is dimensionless.
*/
public boolean isDimensionless();
}