001/*
002 * Units of Measurement Reference Implementation
003 * Copyright (c) 2005-2020, Units of Measurement project.
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.function;
031
032import java.util.function.BiPredicate;
033import java.util.function.BinaryOperator;
034
035import tech.units.indriya.internal.function.simplify.UnitCompositionHandlerYieldingNormalForm;
036
037/**
038 * Functional interface for handling the composition (concatenation) of two unit converters.
039 * 
040 * @author Andi Huber
041 * @author Werner Keil
042 * @version 1.2
043 * @since 2.0
044 */
045public interface ConverterCompositionHandler {
046
047    /**
048     * Takes two converters {@code left}, {@code right} and returns a (not necessarily new) 
049     * converter that is equivalent to the mathematical composition of these:
050     * <p>
051     * compose(left, right) === left o right 
052     * 
053     * <p>
054     * Implementation Note: Instead of using AbstractConverter as parameter 
055     * and result types, this could be generalized to UnitConverter, but that 
056     * would require some careful changes within AbstractConverter itself.
057     *  
058     * @param left
059     * @param right
060     * @param canReduce
061     * @param doReduce
062     * @return
063     */
064    public AbstractConverter compose(
065            AbstractConverter left, 
066            AbstractConverter right,
067            BiPredicate<AbstractConverter, AbstractConverter> canReduce,
068            BinaryOperator<AbstractConverter> doReduce);
069    
070    // -- FACTORIES (BUILT-IN) 
071    
072    /**
073     * @return the default built-in UnitCompositionHandler which is yielding a normal-form, 
074     * required to decide whether two UnitConverters are equivalent
075     */
076    public static ConverterCompositionHandler yieldingNormalForm() {
077        return new UnitCompositionHandlerYieldingNormalForm();
078    }
079
080}