001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 * Licensed to the public under the agreements of the GNU Lesser General Public
007 * License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *      http://www.gnu.org/licenses/lgpl.html
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 * License for the specific language governing permissions and limitations
015 * under the License.
016 */
017
018package org.tquadrat.foundation.value.api;
019
020import static org.apiguardian.api.API.Status.STABLE;
021import static org.tquadrat.foundation.value.api.DimensionedValue.MATH_CONTEXT;
022
023import java.math.BigDecimal;
024import java.util.function.UnaryOperator;
025
026import org.apiguardian.api.API;
027import org.tquadrat.foundation.annotation.ClassVersion;
028
029/**
030 *  <p>{@summary The implementations of this interface are used to give
031 *  (numerical) values a dimension and a measuring unit.} So {@code 3.1415} is
032 *  just a number, but it could also stand for a length
033 *  ({@code 3.1415&nbsp;m}), a time ({@code 3.1415&nbsp;s}) or even the fuel
034 *  consumption of a car ({@code 3.1415&nbsp;l/100&nbsp;km}). Depending on the
035 *  dimension, different values could be equal:</p>
036 *  <pre><code>1.0&nbsp;m == 100.0&nbsp;cm</code></pre>
037 *  <p>and should be treated as such.</p>
038 *  <p>This interface should be implemented as
039 *  {@link Enum enum}s,
040 *  where the enum values are the units, and as such they should provide a
041 *  method to retrieve an {@code enum} value (a unit) by the respective
042 *  {@linkplain #unitSymbol() symbol}.</p>
043 *  <p>It is a generalisation for dimensions that are converted by simple
044 *  division or multiplication of a factor, as for length or speed.</p>
045 *
046 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
047 *  @version $Id: DimensionWithLinearConversion.java 1072 2023-09-30 20:44:38Z tquadrat $
048 *  @since 0.1.0
049 *
050 *  @UMLGraph.link
051 */
052@ClassVersion( sourceVersion = "$Id: DimensionWithLinearConversion.java 1072 2023-09-30 20:44:38Z tquadrat $" )
053@API( status = STABLE, since = "0.1.0" )
054public interface DimensionWithLinearConversion extends Dimension
055{
056        /*-----------*\
057    ====** Constants **========================================================
058        \*-----------*/
059    /**
060     *  Message: Unknown Unit.
061     */
062    public static final String MSG_UnknownUnit = "Unknown unit: %s";
063
064        /*---------*\
065    ====** Methods **==========================================================
066        \*---------*/
067    /**
068     *  <p>{@summary Returns the factor that is used to convert a value from
069     *  this unit to the base unit.}</p>
070     *  <p>For length, if you have to convert a Centimeter value to Meter, you
071     *  will divide that by 100 or multiply it with a <i>factor</i> of
072     *  0.01.</p>
073     *  <p>For the base unit, the factor is 1.0.</p>
074     *
075     *  @return The factor.
076     *
077     *  @see #baseUnit()
078     */
079    public BigDecimal factor();
080
081    /**
082     * {@inheritDoc}
083     */
084    @Override
085    public default UnaryOperator<BigDecimal> fromBase()
086    {
087        final UnaryOperator<BigDecimal> retValue = base -> base.multiply( factor() );
088
089        //---* Done *----------------------------------------------------------
090        return retValue;
091    }   //  fromBase()
092
093    /**
094     *  <p>{@summary Returns the conversion that is used to convert a value
095     *  from this unit to the base unit.}</p>
096     *
097     *  @return The conversion.
098     */
099    @Override
100    public default UnaryOperator<BigDecimal> toBase()
101    {
102        final UnaryOperator<BigDecimal> retValue = value -> value.divide( factor(), MATH_CONTEXT );
103
104        //---* Done *----------------------------------------------------------
105        return retValue;
106    }   //  toBase()
107}
108//  interface DimensionWithLinearConversion
109
110/*
111 *  End of File
112 */