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:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
067 * @author <a href="mailto:steve@unidata.ucar.edu">Steve Emmerson</a>
068 * @author <a href="mailto:martin.desruisseaux@geomatys.com">Martin Desruisseaux</a>
069 * @author <a href="mailto:werner@units.tech">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&lt;?&gt; unit) {<br>
120     *     &nbsp;&nbsp;    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}