001/* 002 * Units of Measurement API 003 * Copyright (c) 2014-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 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 */ 030package javax.measure; 031 032import java.util.List; 033 034/** 035 * A converter of numeric values between different units. 036 * 037 * <p> 038 * Instances of this class are usually obtained through the {@link Unit#getConverterTo(Unit)} method. 039 * </p> 040 * 041 * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a> 042 * @author <a href="mailto:werner@uom.technology">Werner Keil</a> 043 * @author <a href="mailto:martin.desruisseaux@geomatys.com">Martin 044 * Desruisseaux</a> 045 * @author <a href="mailto:thodoris.bais@gmail.com">Thodoris Bais</a> 046 * @author <a href="mailto:ahuber@apache.org">Andi Huber</a> 047 * @version 1.4, May 12, 2019 048 * @since 1.0 049 * 050 * @see Unit 051 * @see <a href="http://en.wikipedia.org/wiki/Conversion_of_units"> Wikipedia: Conversion of units</a> 052 */ 053public interface UnitConverter { 054 055 /** 056 * Indicates if this converter is an identity converter. The identity converter returns its input argument ({@code convert(x) == x}). 057 * <p> 058 * Note: Identity converters are also always 'linear', see {@link UnitConverter#isLinear()}. 059 * </p> 060 * 061 * @return {@code true} if this converter is an identity converter. 062 */ 063 boolean isIdentity(); 064 065 /** 066 * Indicates whether this converter represents a (one-dimensional) linear transformation, that is 067 * a <a href="https://en.wikipedia.org/wiki/Linear_map">linear map (wikipedia)</a> from a one-dimensional 068 * vector space (a scalar) to a one-dimensional vector space. Typically from 'R' to 'R', with 'R' the 069 * real numbers. 070 * 071 * <p> 072 * Given such a 'linear' converter 'A', let 'u', 'v' and 'r' be arbitrary numbers, then the following 073 * must hold by definition: 074 * 075 * <ul> 076 * <li>{@code A(u + v) == A(u) + A(v)}</li> 077 * <li>{@code A(r * u) == r * A(u)}</li> 078 * </ul> 079 * 080 * <p> 081 * Given a second 'linear' converter 'B', commutativity of composition follows by above definition: 082 * 083 * <ul> 084 * <li>{@code (A o B) (u) == (B o A) (u)}</li> 085 * </ul> 086 * 087 * In other words, two 'linear' converters do have the property that {@code A(B(u)) == B(A(u))}, meaning 088 * for 'A' and 'B' the order of their composition does not matter. Expressed as Java code: 089 * 090 * <p> 091 *{@code A.concatenate(B).convert(u) == B.concatenate(A).convert(u)} 092 * </p> 093 * 094 * Note: For composing UnitConverters see also {@link UnitConverter#concatenate(UnitConverter)}. 095 * 096 * @return {@code true} if this converter represents a linear transformation; 097 * {@code false} otherwise. 098 * 099 */ 100 boolean isLinear(); 101 102 /** 103 * Returns the inverse of this converter. If {@code x} is a valid value, then {@code x == inverse().convert(convert(x))} to within the accuracy of 104 * computer arithmetic. 105 * 106 * @return the inverse of this converter. 107 */ 108 UnitConverter inverse(); 109 110 /** 111 * Converts a {@code Number} value. 112 * 113 * @param value 114 * the {@code Number} value to convert. 115 * @return the {@code Number} value after conversion. 116 */ 117 Number convert(Number value); 118 119 /** 120 * Converts a {@code double} value. 121 * 122 * @param value 123 * the numeric value to convert. 124 * @return the {@code double} value after conversion. 125 */ 126 double convert(double value); 127 128 /** 129 * Concatenates this converter with another converter. The resulting converter is equivalent to first converting by the specified converter (right 130 * converter), and then converting by this converter (left converter). 131 * 132 * @param converter 133 * the other converter to concatenate with this converter. 134 * @return the concatenation of this converter with the other converter. 135 */ 136 UnitConverter concatenate(UnitConverter converter); 137 138 /** 139 * <p> 140 * Returns the steps of fundamental converters making up this converter or {@code this} if the converter is a fundamental converter. 141 * </p> 142 * <p> 143 * For example, {@code converter1.getConversionSteps()} returns {@code converter1} while 144 * {@code converter1.concatenate(converter2).getConversionSteps()} returns {@code converter1, converter2}. 145 * </p> 146 * 147 * @return the list of fundamental converters which concatenated make up this converter. 148 */ 149 List<? extends UnitConverter> getConversionSteps(); 150}