javax.measure.Unit Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of unit-api Show documentation
Show all versions of unit-api Show documentation
Units of Measurement Standard - This JSR specifies Java packages for modeling and working with measurement values, quantities and their corresponding units.
The newest version!
/*
* Units of Measurement API
* Copyright (c) 2014-2023, Jean-Marie Dautelle, Werner Keil, Otavio Santana.
*
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions
* and the following disclaimer in the documentation and/or other materials provided with the distribution.
*
* 3. Neither the name of JSR-385 nor the names of its contributors may be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
//
// This source code implements specifications defined by the Java
// Community Process. In order to remain compliant with the specification
// DO NOT add / change / or delete method signatures!
//
package javax.measure;
import java.util.Map;
/**
* Represents a determinate {@linkplain Quantity quantity} (as of length, time, heat, or value) adopted as a standard of measurement.
*
*
* It is helpful to think of instances of this class as recording the history by which they are created. Thus, for example, the string {@code "g/kg"}
* (which is a dimensionless unit) would result from invoking the method {@link #toString()} on a unit that was created by dividing a gram unit by a
* kilogram unit.
*
*
*
* This interface supports the multiplication of offsets units. The result is usually a unit not convertible to its {@linkplain #getSystemUnit()
* system unit}. Such units may appear in derivative quantities. For example Celsius per meter is an unit of gradient, which is common in atmospheric
* and oceanographic research.
*
*
*
* Units raised at non-integral powers are not supported. For example, {@code LITRE.root(2)} raises an {@code ArithmeticException}, but
* {@code HECTARE.root(2)} returns {@code HECTOMETRE} (100 metres).
*
*
*
* Unit instances shall be immutable.
*
*
* @param
* The type of the quantity measured by this unit.
*
* @author Jean-Marie Dautelle
* @author Steve Emmerson
* @author Martin Desruisseaux
* @author Werner Keil
* @version 2.4, November 11, 2020
* @since 1.0
*
* @see Wikipedia: Units of measurement
*/
public interface Unit> {
/*******************/
/** Units Queries **/
/*******************/
/**
* Returns the symbol (if any) of this unit. This method returns {@code null} if this unit has no specific symbol associated with.
*
* @return this unit symbol, or {@code null} if this unit has not specific symbol associated with (e.g. product of units).
*
* @see #toString()
* @see javax.measure.format.UnitFormat
*/
String getSymbol();
/**
* Returns the name (if any) of this unit. This method returns {@code null} if this unit has no specific name associated with.
*
* @return this unit name, or {@code null} if this unit has not specific name associated with (e.g. product of units).
*
* @see #toString()
* @see javax.measure.format.UnitFormat
*/
String getName();
/**
* Returns the dimension of this unit. Two units {@code u1} and {@code u2} are {@linkplain #isCompatible(Unit) compatible} if and only if
* {@code u1.getDimension().equals(u2.getDimension())}.
*
* @return the dimension of this unit.
*
* @see #isCompatible(Unit)
*/
Dimension getDimension();
/**
* Returns the unscaled system unit from which this unit is derived. System units are either base units, {@linkplain #alternate(String) alternate}
* units or product of rational powers of system units.
*
*
* Because the system unit is unique by quantity type, it can be be used to identify the quantity given the unit. For example:
*
*
* static boolean isAngularSpeed(Unit<?> unit) {
* return unit.getSystemUnit().equals(RADIAN.divide(SECOND));
* }
* assert isAngularSpeed(REVOLUTION.divide(MINUTE)); // Returns true.
*
*
* @return the system unit this unit is derived from, or {@code this} if this unit is a system unit.
*/
Unit getSystemUnit();
/**
* Returns the base units and their exponent whose product is this unit, or {@code null} if this unit is a base unit (not a product of existing
* units).
*
* @return the base units and their exponent making up this unit.
*/
Map, Integer> getBaseUnits();
/**
* Indicates if this unit is compatible with the unit specified. Units don't need to be equal to be compatible. For example (assuming {@code ONE}
* is a dimensionless unit):
*
*
* RADIAN.equals(ONE) == false
* RADIAN.isCompatible(ONE) == true
* RADIAN.isEquivalentTo(ONE) doesn't compile
*
*
* @param that
* the other unit to compare for compatibility.
* @return {@code this.getDimension().equals(that.getDimension())}
*
* @see #getDimension()
*/
boolean isCompatible(Unit that);
/**
* Indicates if this unit represents the same quantity than the given unit, ignoring name and symbols.
* Two units are equivalent if the {@linkplain #getConverterTo(Unit) conversion} between them is identity.
*
*
* Unlike {@link #isCompatible(Unit)} an equivalence check requires both units to be strictly type-compatible,
* because it makes no sense to compare e.g. {@code gram} and {@code mm} for equivalence.
* By contrast, the compatibility check can works across different quantity types.
*
*
* @param that the {@code Unit} to be compared with this instance.
* @return {@code true} if {@code that \u2261 this}.
* @throws NullPointerException if the unit is null
*
* @see Cambridge Dictionary: equivalent
* @see LEXICO: equivalent
* @since 2.1
*/
boolean isEquivalentTo(Unit that);
/**
* Casts this unit to a parameterized unit of specified nature or throw a {@code ClassCastException} if the dimension of the specified quantity and
* this unit's dimension do not match. For example:
*
*
* {@literal Unit} C = METRE.multiply(299792458).divide(SECOND).asType(Speed.class);
*
*
* @param
* The type of the quantity measured by the unit.
* @param type
* the quantity class identifying the nature of the unit.
* @return this unit parameterized with the specified type.
* @throws ClassCastException
* if the dimension of this unit is different from the specified quantity dimension.
*/
> Unit asType(Class type) throws ClassCastException;
/**
* Returns a converter of numeric values from this unit to another unit of same type. This method performs the same work as
* {@link #getConverterToAny(Unit)} without raising checked exception.
*
* @param that
* the unit of same type to which to convert the numeric values.
* @return the converter from this unit to {@code that} unit.
* @throws UnconvertibleException
* if a converter cannot be constructed.
*
* @see #getConverterToAny(Unit)
*/
UnitConverter getConverterTo(Unit that) throws UnconvertibleException;
/**
* Returns a converter from this unit to the specified unit of type unknown. This method can be used when the quantity type of the specified unit is
* unknown at compile-time or when dimensional analysis allows for conversion between units of different type.
*
*
* To convert to a unit having the same parameterized type, {@link #getConverterTo(Unit)} is preferred (no checked exception raised).
*
*
* @param that
* the unit to which to convert the numeric values.
* @return the converter from this unit to {@code that} unit.
* @throws IncommensurableException
* if this unit is not {@linkplain #isCompatible(Unit) compatible} with {@code that} unit.
* @throws UnconvertibleException
* if a converter cannot be constructed.
*
* @see #getConverterTo(Unit)
* @see #isCompatible(Unit)
*/
UnitConverter getConverterToAny(Unit that) throws IncommensurableException, UnconvertibleException;
/**********************/
/** Units Operations **/
/**********************/
/**
* Returns a system unit equivalent to this unscaled standard unit but used in expressions to distinguish between quantities of a different nature
* but of the same dimensions.
*
*
* Examples of alternate units:
*
*
*
* {@literal Unit} RADIAN = ONE.alternate("rad").asType(Angle.class);
* {@literal Unit} NEWTON = METRE.multiply(KILOGRAM).divide(SECOND.pow(2)).alternate("N").asType(Force.class);
* {@literal Unit} PASCAL = NEWTON.divide(METRE.pow(2)).alternate("Pa").asType(Pressure.class);
*
*
* @param symbol
* the new symbol for the alternate unit.
* @return the alternate unit.
* @throws IllegalArgumentException
* if this unit is not an unscaled standard unit.
* @throws MeasurementException
* if the specified symbol is not valid or is already associated to a different unit.
*/
Unit alternate(String symbol);
/**
* Returns the result of setting the origin of the scale of measurement to the given value. The returned unit is convertible with all units that are
* convertible with this unit. For example the following code:
*
*
* CELSIUS = KELVIN.shift(273.15);
*
*
* creates a new unit where 0°C (the origin of the new unit) is equals to 273.15 K. Converting from the old unit to the new one is equivalent to
* subtracting the offset to the value in the old unit.
*
* @param offset
* the offset added (expressed in this unit).
* @return this unit offset by the specified value.
* @since 2.0
*/
Unit shift(Number offset);
/**
* Returns the result of setting the origin of the scale of measurement to the given value. The returned unit is convertible with all units that are
* convertible with this unit. For example the following code:
*
*
* CELSIUS = KELVIN.shift(273.15);
*
*
* creates a new unit where 0°C (the origin of the new unit) is equals to 273.15 K. Converting from the old unit to the new one is equivalent to
* subtracting the offset to the value in the old unit.
*
* @param offset
* the offset added (expressed in this unit).
* @return this unit offset by the specified value.
*/
Unit shift(double offset);
/**
* Returns the result of multiplying this unit by the specified factor. If the factor is an integer value, the multiplication is exact
* (recommended). For example:
*
*
* FOOT = METRE.multiply(3048).divide(10000); // Exact definition.
* ELECTRON_MASS = KILOGRAM.multiply(9.10938188e-31); // Approximation.
*
*
* @param multiplier
* the multiplier
* @return this unit scaled by the specified multiplier.
* @since 2.0
*/
Unit multiply(Number multiplier);
/**
* Returns the result of multiplying this unit by the specified factor. For example:
*
*
* FOOT = METRE.multiply(3048).divide(10000); // Exact definition.
* ELECTRON_MASS = KILOGRAM.multiply(9.10938188e-31); // Approximation.
*
*
* @param multiplier
* the multiplier
* @return this unit scaled by the specified multiplier.
*/
Unit multiply(double multiplier);
/**
* Returns the product of this unit with the one specified.
*
* @param multiplier
* the unit multiplier.
* @return {@code this * multiplier}
*/
Unit multiply(Unit multiplier);
/**
* Returns the reciprocal (multiplicative inverse) of this unit.
*
* @return {@code 1 / this}
* @see Wikipedia: Multiplicative inverse
*/
Unit inverse();
/**
* Returns the result of dividing this unit by a divisor. If the factor is an integer value, the division is exact. For example:
*
*
* GRAM = KILOGRAM.divide(1000); // Exact definition.
*
*
* @param divisor
* the divisor value.
* @return this unit divided by the specified divisor.
* @since 2.0
*/
Unit divide(Number divisor);
/**
* Returns the result of dividing this unit by an approximate divisor. For example:
*
*
* GRAM = KILOGRAM.divide(1000d);
*
*
* @param divisor
* the divisor value.
* @return this unit divided by the specified divisor.
*/
Unit divide(double divisor);
/**
* Returns the quotient of this unit with the one specified.
*
* @param divisor
* the unit divisor.
* @return {@code this / divisor}
*/
Unit divide(Unit divisor);
/**
* Returns an unit that is the n-th (integer) root of this unit. Equivalent to the mathematical expression {@code unit^(1/n)}.
*
* @param n
* an integer giving the root's order as in 'n-th root'
* @return the n-th root of this unit.
* @throws ArithmeticException
* if {@code n == 0} or if this operation would result in an unit with a fractional exponent.
*/
Unit root(int n);
/**
* Returns an unit raised to the n-th (integer) power of this unit. Equivalent to the mathematical expression {@code unit^n}.
*
* @param n
* the exponent.
* @return the result of raising this unit to the exponent.
*/
Unit pow(int n);
/**
* Returns the unit derived from this unit using the specified converter. The converter does not need to be linear. For example:
*
*
* {@literal Unit} DECIBEL = Unit.ONE.transform(
* new LogConverter(10).inverse().concatenate(
* new RationalConverter(1, 10)));
*
*
* @param operation
* the converter from the transformed unit to this unit.
* @return the unit after the specified transformation.
*/
Unit transform(UnitConverter operation);
/**
* Returns a string representation of this unit. The string representation may be the unit {@linkplain #getSymbol() symbol}, or may be some
* representation of {@linkplain #getBaseUnits() product units}, multiplication factor and offset if any.
*
*
* The string may be localized at implementation choice by the means of a particular device and platform.
*
*
* @return the string representation of this unit.
*
* @see #getSymbol()
* @see javax.measure.format.UnitFormat
*/
@Override
String toString();
/**
* Returns a new unit equal to this unit prefixed by the specified {@code prefix}.
*
* @param prefix
* the prefix to apply on this unit.
* @return the unit with the given prefix applied.
* @since 2.0
*/
Unit prefix(Prefix prefix);
}