001/* 002 * Units of Measurement API 003 * Copyright (c) 2014-2021, Jean-Marie Dautelle, Werner Keil, Otavio Santana. 004 * 005 * All rights reserved. 006 * 007 * Redistribution and use in source and binary forms, with or without modification, 008 * are permitted provided that the following conditions are met: 009 * 010 * 1. Redistributions of source code must retain the above copyright notice, 011 * this list of conditions and the following disclaimer. 012 * 013 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions 014 * and the following disclaimer in the documentation and/or other materials provided with the distribution. 015 * 016 * 3. Neither the name of JSR-385 nor the names of its contributors may be used to endorse or promote products 017 * derived from this software without specific prior written permission. 018 * 019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 021 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 022 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 023 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 024 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 025 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 026 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 027 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 028 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 029 */ 030// 031// This source code implements specifications defined by the Java 032// Community Process. In order to remain compliant with the specification 033// DO NOT add / change / or delete method signatures! 034// 035package javax.measure; 036 037import java.util.Map; 038 039/** 040 * Represents a determinate {@linkplain Quantity quantity} (as of length, time, heat, or value) adopted as a standard of measurement. 041 * 042 * <p> 043 * 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"} 044 * (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 045 * kilogram unit. 046 * </p> 047 * 048 * <p> 049 * This interface supports the multiplication of offsets units. The result is usually a unit not convertible to its {@linkplain #getSystemUnit() 050 * system unit}. Such units may appear in derivative quantities. For example Celsius per meter is an unit of gradient, which is common in atmospheric 051 * and oceanographic research. 052 * </p> 053 * 054 * <p> 055 * Units raised at non-integral powers are not supported. For example, {@code LITRE.root(2)} raises an {@code ArithmeticException}, but 056 * {@code HECTARE.root(2)} returns {@code HECTOMETRE} (100 metres). 057 * </p> 058 * 059 * <p> 060 * Unit instances shall be immutable. 061 * </p> 062 * 063 * @param <Q> 064 * The type of the quantity measured by this unit. 065 * 066 * @author <a href="mailto:[email protected]">Jean-Marie Dautelle</a> 067 * @author <a href="mailto:[email protected]">Steve Emmerson</a> 068 * @author <a href="mailto:[email protected]">Martin Desruisseaux</a> 069 * @author <a href="mailto:[email protected]">Werner Keil</a> 070 * @version 2.4, November 11, 2020 071 * @since 1.0 072 * 073 * @see <a href="http://en.wikipedia.org/wiki/Units_of_measurement">Wikipedia: Units of measurement</a> 074 */ 075public interface Unit<Q extends Quantity<Q>> { 076 077 /*******************/ 078 /** Units Queries **/ 079 /*******************/ 080 081 /** 082 * Returns the symbol (if any) of this unit. This method returns {@code null} if this unit has no specific symbol associated with. 083 * 084 * @return this unit symbol, or {@code null} if this unit has not specific symbol associated with (e.g. product of units). 085 * 086 * @see #toString() 087 * @see javax.measure.format.UnitFormat 088 */ 089 String getSymbol(); 090 091 /** 092 * Returns the name (if any) of this unit. This method returns {@code null} if this unit has no specific name associated with. 093 * 094 * @return this unit name, or {@code null} if this unit has not specific name associated with (e.g. product of units). 095 * 096 * @see #toString() 097 * @see javax.measure.format.UnitFormat 098 */ 099 String getName(); 100 101 /** 102 * Returns the dimension of this unit. Two units {@code u1} and {@code u2} are {@linkplain #isCompatible(Unit) compatible} if and only if 103 * {@code u1.getDimension().equals(u2.getDimension())}. 104 * 105 * @return the dimension of this unit. 106 * 107 * @see #isCompatible(Unit) 108 */ 109 Dimension getDimension(); 110 111 /** 112 * Returns the unscaled system unit from which this unit is derived. System units are either base units, {@linkplain #alternate(String) alternate} 113 * units or product of rational powers of system units. 114 * 115 * <p> 116 * Because the system unit is unique by quantity type, it can be be used to identify the quantity given the unit. For example: 117 * </p> 118 * <code> 119 * static boolean isAngularSpeed(Unit<?> unit) {<br> 120 * return unit.getSystemUnit().equals(RADIAN.divide(SECOND));<br> 121 * }<br> 122 * assert isAngularSpeed(REVOLUTION.divide(MINUTE)); // Returns true.<br><br> 123 * </code> 124 * 125 * @return the system unit this unit is derived from, or {@code this} if this unit is a system unit. 126 */ 127 Unit<Q> getSystemUnit(); 128 129 /** 130 * 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 131 * units). 132 * 133 * @return the base units and their exponent making up this unit. 134 */ 135 Map<? extends Unit<?>, Integer> getBaseUnits(); 136 137 /** 138 * 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} 139 * is a dimensionless unit):<br> 140 * 141 * <code> 142 * RADIAN.equals(ONE) == false<br> 143 * RADIAN.isCompatible(ONE) == true<br> 144 * RADIAN.isEquivalentTo(ONE) <b>doesn't compile</b><br> 145 * </code> 146 * 147 * @param that 148 * the other unit to compare for compatibility. 149 * @return {@code this.getDimension().equals(that.getDimension())} 150 * 151 * @see #getDimension() 152 */ 153 boolean isCompatible(Unit<?> that); 154 155 /** 156 * Compares two instances of {@code Unit<Q>}, doing the conversion of unit if necessary. 157 * Unlike {@link #isCompatible(Unit)} an equivalence check requires both units to be strictly type-compatible, 158 * because it makes no sense to compare e.g. {@code gram} and {@code mm} for equivalence. While the compatibility check also works across different quantity types. 159 * 160 * @param that the {@code Unit<Q>} to be compared with this instance. 161 * @return {@code true} if {@code that \u2261 this}. 162 * @throws NullPointerException if the unit is null 163 * 164 * @see <a href= "https://dictionary.cambridge.org/dictionary/english/equivalent">Cambridge Dictionary: equivalent</a> 165 * @see <a href= "https://www.lexico.com/en/definition/equivalent">LEXICO: equivalent</a> 166 * @since 2.1 167 */ 168 boolean isEquivalentTo(Unit<Q> that); 169 170 /** 171 * Casts this unit to a parameterized unit of specified nature or throw a {@code ClassCastException} if the dimension of the specified quantity and 172 * this unit's dimension do not match. For example:<br> 173 * 174 * <code> 175 * {@literal Unit<Speed>} C = METRE.multiply(299792458).divide(SECOND).asType(Speed.class); 176 * </code> 177 * 178 * @param <T> 179 * The type of the quantity measured by the unit. 180 * @param type 181 * the quantity class identifying the nature of the unit. 182 * @return this unit parameterized with the specified type. 183 * @throws ClassCastException 184 * if the dimension of this unit is different from the specified quantity dimension. 185 */ 186 <T extends Quantity<T>> Unit<T> asType(Class<T> type) throws ClassCastException; 187 188 /** 189 * Returns a converter of numeric values from this unit to another unit of same type. This method performs the same work as 190 * {@link #getConverterToAny(Unit)} without raising checked exception. 191 * 192 * @param that 193 * the unit of same type to which to convert the numeric values. 194 * @return the converter from this unit to {@code that} unit. 195 * @throws UnconvertibleException 196 * if a converter cannot be constructed. 197 * 198 * @see #getConverterToAny(Unit) 199 */ 200 UnitConverter getConverterTo(Unit<Q> that) throws UnconvertibleException; 201 202 /** 203 * 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 204 * unknown at compile-time or when dimensional analysis allows for conversion between units of different type. 205 * 206 * <p> 207 * To convert to a unit having the same parameterized type, {@link #getConverterTo(Unit)} is preferred (no checked exception raised). 208 * </p> 209 * 210 * @param that 211 * the unit to which to convert the numeric values. 212 * @return the converter from this unit to {@code that} unit. 213 * @throws IncommensurableException 214 * if this unit is not {@linkplain #isCompatible(Unit) compatible} with {@code that} unit. 215 * @throws UnconvertibleException 216 * if a converter cannot be constructed. 217 * 218 * @see #getConverterTo(Unit) 219 * @see #isCompatible(Unit) 220 */ 221 UnitConverter getConverterToAny(Unit<?> that) throws IncommensurableException, UnconvertibleException; 222 223 /**********************/ 224 /** Units Operations **/ 225 /**********************/ 226 227 /** 228 * Returns a system unit equivalent to this unscaled standard unit but used in expressions to distinguish between quantities of a different nature 229 * but of the same dimensions. 230 * 231 * <p> 232 * Examples of alternate units: 233 * </p> 234 * 235 * <code> 236 * {@literal Unit<Angle>} RADIAN = ONE.alternate("rad").asType(Angle.class);<br> 237 * {@literal Unit<Force>} NEWTON = METRE.multiply(KILOGRAM).divide(SECOND.pow(2)).alternate("N").asType(Force.class);<br> 238 * {@literal Unit<Pressure>} PASCAL = NEWTON.divide(METRE.pow(2)).alternate("Pa").asType(Pressure.class);<br> 239 * </code> 240 * 241 * @param symbol 242 * the new symbol for the alternate unit. 243 * @return the alternate unit. 244 * @throws IllegalArgumentException 245 * if this unit is not an unscaled standard unit. 246 * @throws MeasurementException 247 * if the specified symbol is not valid or is already associated to a different unit. 248 */ 249 Unit<Q> alternate(String symbol); 250 251 /** 252 * 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 253 * convertible with this unit. For example the following code:<br> 254 * 255 * <code> 256 * CELSIUS = KELVIN.shift(273.15); 257 * </code> 258 * 259 * 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 260 * <em>subtracting</em> the offset to the value in the old unit. 261 * 262 * @param offset 263 * the offset added (expressed in this unit). 264 * @return this unit offset by the specified value. 265 * @since 2.0 266 */ 267 Unit<Q> shift(Number offset); 268 269 /** 270 * 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 271 * convertible with this unit. For example the following code:<br> 272 * 273 * <code> 274 * CELSIUS = KELVIN.shift(273.15); 275 * </code> 276 * 277 * 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 278 * <em>subtracting</em> the offset to the value in the old unit. 279 * 280 * @param offset 281 * the offset added (expressed in this unit). 282 * @return this unit offset by the specified value. 283 */ 284 Unit<Q> shift(double offset); 285 286 /** 287 * Returns the result of multiplying this unit by the specified factor. If the factor is an integer value, the multiplication is exact 288 * (recommended). For example:<br> 289 * 290 * <code> 291 * FOOT = METRE.multiply(3048).divide(10000); // Exact definition.<br> 292 * ELECTRON_MASS = KILOGRAM.multiply(9.10938188e-31); // Approximation. 293 * </code> 294 * 295 * @param multiplier 296 * the multiplier 297 * @return this unit scaled by the specified multiplier. 298 * @since 2.0 299 */ 300 Unit<Q> multiply(Number multiplier); 301 302 /** 303 * Returns the result of multiplying this unit by the specified factor. For example:<br> 304 * 305 * <code> 306 * FOOT = METRE.multiply(3048).divide(10000); // Exact definition.<br> 307 * ELECTRON_MASS = KILOGRAM.multiply(9.10938188e-31); // Approximation. 308 * </code> 309 * 310 * @param multiplier 311 * the multiplier 312 * @return this unit scaled by the specified multiplier. 313 */ 314 Unit<Q> multiply(double multiplier); 315 316 /** 317 * Returns the product of this unit with the one specified. 318 * 319 * @param multiplier 320 * the unit multiplier. 321 * @return {@code this * multiplier} 322 */ 323 Unit<?> multiply(Unit<?> multiplier); 324 325 /** 326 * Returns the reciprocal (multiplicative inverse) of this unit. 327 * 328 * @return {@code 1 / this} 329 * @see <a href="https://en.wikipedia.org/wiki/Multiplicative_inverse">Wikipedia: Multiplicative inverse</a> 330 */ 331 Unit<?> inverse(); 332 333 /** 334 * Returns the result of dividing this unit by a divisor. If the factor is an integer value, the division is exact. For example:<br> 335 * 336 * <code> 337 * GRAM = KILOGRAM.divide(1000); // Exact definition. 338 * </code> 339 * 340 * @param divisor 341 * the divisor value. 342 * @return this unit divided by the specified divisor. 343 * @since 2.0 344 */ 345 Unit<Q> divide(Number divisor); 346 347 /** 348 * Returns the result of dividing this unit by an approximate divisor. For example:<br> 349 * 350 * <code> 351 * GRAM = KILOGRAM.divide(1000d); 352 * </code> 353 * 354 * @param divisor 355 * the divisor value. 356 * @return this unit divided by the specified divisor. 357 */ 358 Unit<Q> divide(double divisor); 359 360 /** 361 * Returns the quotient of this unit with the one specified. 362 * 363 * @param divisor 364 * the unit divisor. 365 * @return {@code this / divisor} 366 */ 367 Unit<?> divide(Unit<?> divisor); 368 369 /** 370 * Returns an unit that is the n-th (integer) root of this unit. Equivalent to the mathematical expression {@code unit^(1/n)}. 371 * 372 * @param n 373 * an integer giving the root's order as in 'n-th root' 374 * @return the n-th root of this unit. 375 * @throws ArithmeticException 376 * if {@code n == 0} or if this operation would result in an unit with a fractional exponent. 377 */ 378 Unit<?> root(int n); 379 380 /** 381 * Returns an unit raised to the n-th (integer) power of this unit. Equivalent to the mathematical expression {@code unit^n}. 382 * 383 * @param n 384 * the exponent. 385 * @return the result of raising this unit to the exponent. 386 */ 387 Unit<?> pow(int n); 388 389 /** 390 * Returns the unit derived from this unit using the specified converter. The converter does not need to be linear. For example:<br> 391 * 392 * <pre> 393 * {@literal Unit<Dimensionless>} DECIBEL = Unit.ONE.transform( 394 * new LogConverter(10).inverse().concatenate( 395 * new RationalConverter(1, 10))); 396 * </pre> 397 * 398 * @param operation 399 * the converter from the transformed unit to this unit. 400 * @return the unit after the specified transformation. 401 */ 402 Unit<Q> transform(UnitConverter operation); 403 404 /** 405 * Returns a string representation of this unit. The string representation may be the unit {@linkplain #getSymbol() symbol}, or may be some 406 * representation of {@linkplain #getBaseUnits() product units}, multiplication factor and offset if any. 407 * 408 * <p> 409 * The string may be localized at implementation choice by the means of a particular device and platform. 410 * </p> 411 * 412 * @return the string representation of this unit. 413 * 414 * @see #getSymbol() 415 * @see javax.measure.format.UnitFormat 416 */ 417 @Override 418 String toString(); 419 420 /** 421 * Returns a new unit equal to this unit prefixed by the specified {@code prefix}. 422 * 423 * @param prefix 424 * the prefix to apply on this unit. 425 * @return the unit with the given prefix applied. 426 * @since 2.0 427 */ 428 Unit<Q> prefix(Prefix prefix); 429}