diff options
Diffstat (limited to 'src/org/unitConverter/unit/OperatableUnit.java')
| -rw-r--r-- | src/org/unitConverter/unit/OperatableUnit.java | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/src/org/unitConverter/unit/OperatableUnit.java b/src/org/unitConverter/unit/OperatableUnit.java new file mode 100644 index 0000000..ae11c41 --- /dev/null +++ b/src/org/unitConverter/unit/OperatableUnit.java @@ -0,0 +1,169 @@ +/** + * Copyright (C) 2019 Adrien Hopkins + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <https://www.gnu.org/licenses/>. + */ +package org.unitConverter.unit; + +/** + * A unit that can be added, subtracted, multiplied or divided by another operatable unit, and raised to an integer + * exponent. + * <p> + * In order to use two units in an operation, they must be part of the same unit system. In addition, in order for two + * units to add or subtract, they must measure the same dimension. + * </p> + * <p> + * It is okay for an operation to throw a {@code ClassCastException} if the operator's class cannot operate with another + * class. However, all classes that implement this interface should be able to interoperate with {@code BaseUnit} and + * {@code LinearUnit}. + * </p> + * + * @author Adrien Hopkins + * @since 2019-03-17 + */ +public interface OperatableUnit extends Unit { + /** + * Returns the quotient of this unit and another. + * <p> + * Two units can be divided if they are part of the same unit system. If {@code divisor} does not meet this + * condition, an {@code IllegalArgumentException} should be thrown. + * </p> + * <p> + * It is okay for a unit to throw a {@code ClassCastException} if it cannot operate with {@code divisor}'s class. + * However, all classes that implement this interface should be able to interoperate with {@code BaseUnit} and + * {@code LinearUnit}. + * </p> + * + * @param divisor + * unit to divide by + * @return quotient + * @throws IllegalArgumentException + * if {@code divisor} is not compatible for division as described above + * @throws NullPointerException + * if {@code divisor} is null + * @throws ClassCastException + * if {@code divisor}'s class is incompatible with this unit's class + * @since 2019-03-17 + */ + default OperatableUnit dividedBy(final OperatableUnit divisor) { + return this.times(divisor.reciprocal()); + } + + /** + * Returns the difference of this unit and another. + * <p> + * Two units can be subtracted if they meet the following conditions: + * <ul> + * <li>The two units are part of the same UnitSystem.</li> + * <li>The two units have the same {@code dimension}.</li> + * </ul> + * If {@code subtrahend} does not meet these conditions, an {@code IllegalArgumentException} should be thrown. + * </p> + * <p> + * It is okay for a unit to throw a {@code ClassCastException} if it cannot operate with {@code subtrahend}'s class. + * However, all classes that implement this interface should be able to interoperate with {@code BaseUnit} and + * {@code LinearUnit}. + * </p> + * + * @param subtrahend + * unit to subtract + * @return difference + * @throws IllegalArgumentException + * if {@code subtrahend} is not compatible for subtraction as described above + * @throws NullPointerException + * if {@code subtrahend} is null + * @throws ClassCastException + * if {@code subtrahend}'s class is incompatible with this unit's class + * @since 2019-03-17 + */ + default OperatableUnit minus(final OperatableUnit subtrahend) { + return this.plus(subtrahend.negated()); + } + + /** + * @return this unit negated, i.e. -this + * @since 2019-03-17 + */ + OperatableUnit negated(); + + /** + * Returns the sum of this unit and another. + * <p> + * Two units can be added if they meet the following conditions: + * <ul> + * <li>The two units are part of the same UnitSystem.</li> + * <li>The two units have the same {@code dimension}.</li> + * </ul> + * If {@code addend} does not meet these conditions, an {@code IllegalArgumentException} should be thrown. + * </p> + * <p> + * It is okay for a unit to throw a {@code ClassCastException} if it cannot operate with {@code addend}'s class. + * However, all classes that implement this interface should be able to interoperate with {@code BaseUnit} and + * {@code LinearUnit}. + * </p> + * + * @param addend + * unit to add + * @return sum + * @throws IllegalArgumentException + * if {@code addend} is not compatible for addition as described above + * @throws NullPointerException + * if {@code addend} is null + * @throws ClassCastException + * if {@code addend}'s class is incompatible with this unit's class + * @since 2019-03-17 + */ + OperatableUnit plus(OperatableUnit addend); + + /** + * @return reciprocal of this unit + * @since 2019-03-17 + */ + OperatableUnit reciprocal(); + + /** + * Returns the product of this unit and another. + * <p> + * Two units can be multiplied if they are part of the same unit system. If {@code multiplier} does not meet this + * condition, an {@code IllegalArgumentException} should be thrown. + * </p> + * <p> + * It is okay for a unit to throw a {@code ClassCastException} if it cannot operate with {@code multiplier}'s class. + * However, all classes that implement this interface should be able to interoperate with {@code BaseUnit} and + * {@code LinearUnit}. + * </p> + * + * @param multiplier + * unit to multiply by + * @return product + * @throws IllegalArgumentException + * if {@code multiplier} is not compatible for multiplication as described above + * @throws NullPointerException + * if {@code multiplier} is null + * @throws ClassCastException + * if {@code multiplier}'s class is incompatible with this unit's class + * @since 2019-03-17 + */ + OperatableUnit times(OperatableUnit multiplier); + + /** + * Returns the result of raising this unit to the exponent {@code exponent}. + * + * @param exponent + * exponent to exponentiate by + * @return result of exponentiation + * @since 2019-03-17 + */ + OperatableUnit toExponent(int exponent); +} |