001/*
002 * Units of Measurement Reference Implementation
003 * Copyright (c) 2005-2023, 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, Indriya nor the names of their 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 */
030package tech.units.indriya;
031
032import java.io.Serializable;
033
034import javax.measure.Quantity;
035import javax.measure.Unit;
036
037import tech.uom.lib.common.function.QuantityConverter;
038
039/**
040 * Quantity that adapts Comparable to the {@link javax.measure.Quantity Quantity} interface.
041 * For use in other quantities, when supposed to work on Comparables.
042 * 
043 * It extends {@link javax.measure.Quantity Quantity} with {@linkplain Comparable} and {@linkplain Serializable }
044 * 
045 * @see {@link javax.measure.Quantity Quantity}
046 * @author otaviojava
047 * @author werner
048 * @param <Q> the quantity type
049 * @version 2.3, November 21, 2020
050 * @since 1.0
051 */
052public interface ComparableQuantity<Q extends Quantity<Q>> extends Quantity<Q>, Comparable<Quantity<Q>>, QuantityConverter<Q>, Serializable {
053
054  /**
055   * @see Quantity#add(Quantity)
056   */
057  ComparableQuantity<Q> add(Quantity<Q> that);
058
059  /**
060   * @see Quantity#subtract(Quantity)
061   */
062  ComparableQuantity<Q> subtract(Quantity<Q> that);
063
064  /**
065   * @see Quantity#divide(Quantity)
066   */
067  ComparableQuantity<?> divide(Quantity<?> that);
068
069  /**
070   * @see Quantity#divide(Number)
071   */
072  ComparableQuantity<Q> divide(Number that);
073
074  /**
075   * @see Quantity#multiply(Quantity)
076   */
077  ComparableQuantity<?> multiply(Quantity<?> multiplier);
078
079  /**
080   * @see Quantity#multiply(Number)
081   */
082  ComparableQuantity<Q> multiply(Number multiplier);
083
084  /**
085   * @see Quantity#inverse()
086   */
087  ComparableQuantity<?> inverse();
088
089  /**
090   * invert and already cast to defined quantityClass
091   * 
092   * @param quantityClass
093   *          Quantity to be converted
094   * @see Quantity#inverse()
095   * @see Quantity#asType(Class)
096   */
097  <T extends Quantity<T>> ComparableQuantity<T> inverse(Class<T> quantityClass);
098
099  /**
100   * @see Quantity#to(Unit)
101   */
102  ComparableQuantity<Q> to(Unit<Q> unit);
103
104  /**
105   * @see Quantity#asType(Class)
106   */
107  <T extends Quantity<T>> ComparableQuantity<T> asType(Class<T> type) throws ClassCastException;
108
109  /**
110   * Compares two instances of {@link Quantity <Q>}. Conversion of unit can happen if necessary
111   *
112   * @param that
113   *          the {@code quantity<Q>} to be compared with this instance.
114   * @return {@code true} if {@code that > this}.
115   * @throws NullPointerException
116   *           if the that is null
117   */
118  boolean isGreaterThan(Quantity<Q> that);
119
120  /**
121   * Compares two instances of {@link Quantity <Q>}, doing the conversion of unit if necessary.
122   *
123   * @param that
124   *          the {@code quantity<Q>} to be compared with this instance.
125   * @return {@code true} if {@code that >= this}.
126   * @throws NullPointerException
127   *           if the that is null
128   */
129  boolean isGreaterThanOrEqualTo(Quantity<Q> that);
130
131  /**
132   * Compares two instances of {@link Quantity <Q>}, doing the conversion of unit if necessary.
133   *
134   * @param that
135   *          the {@code quantity<Q>} to be compared with this instance.
136   * @return {@code true} if {@code that < this}.
137   * @throws NullPointerException
138   *           if the quantity is null
139   */
140  boolean isLessThan(Quantity<Q> that);
141
142  /**
143   * Compares two instances of {@link Quantity <Q>}, doing the conversion of unit if necessary.
144   *
145   * @param that
146   *          the {@code quantity<Q>} to be compared with this instance.
147   * @return {@code true} if {@code that < this}.
148   * @throws NullPointerException
149   *           if the quantity is null
150   */
151  boolean isLessThanOrEqualTo(Quantity<Q> that);
152
153  /**
154   * Multiply and cast the {@link ComparableQuantity}
155   * 
156   * @param that
157   *          quantity to be multiplied
158   * @param asTypeQuantity
159   *          quantity to be converted
160   * @return the QuantityOperations multiplied and converted
161   * @see Quantity#divide(Quantity)
162   * @see Quantity#asType(Class)
163   * @exception NullPointerException
164   */
165  <T extends Quantity<T>, E extends Quantity<E>> ComparableQuantity<E> divide(Quantity<T> that, Class<E> asTypeQuantity);
166
167  /**
168   * Divide and cast the {@link ComparableQuantity}
169   * 
170   * @param that
171   *          quantity to be divided
172   * @param asTypeQuantity
173   *          quantity to be converted
174   * @return the QuantityOperations multiplied and converted
175   * @see QuantityOperations
176   * @see QuantityOperations#of(Quantity, Class)
177   * @see Quantity#asType(Class)
178   * @see Quantity#multiply(Quantity)
179   * @exception NullPointerException
180   */
181  <T extends Quantity<T>, E extends Quantity<E>> ComparableQuantity<E> multiply(Quantity<T> that, Class<E> asTypeQuantity);
182}