001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.function;
020
021import static org.apiguardian.api.API.Status.STABLE;
022import static org.tquadrat.foundation.lang.Objects.requireNonNullArgument;
023
024import java.util.function.Function;
025
026import org.apiguardian.api.API;
027import org.tquadrat.foundation.annotation.ClassVersion;
028
029/**
030 *  <p>{@summary Represents an operation that accepts three input arguments and
031 *  produces a result.} This is the three-arity specialisation of
032 *  {@link java.util.function.Function}.</p>
033 *  <p>This is a
034 *  {@linkplain java.lang.FunctionalInterface functional interface}
035 *  whose functional method is
036 *  {@link #apply(Object,Object,Object)}.</p>
037 *
038 *  @param  <A> The type of the first argument to the function.
039 *  @param  <B> The type of the second argument to the function.
040 *  @param  <C> The type of the third argument to the function.
041 *  @param  <R> The type of the result of the function.
042 *
043 *  @see java.util.function.Function
044 *  @see java.util.function.BiFunction
045 *
046 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
047 *  @version $Id: TriFunction.java 1060 2023-09-24 19:21:40Z tquadrat $
048 *  @since 0.0.5
049 *
050 *  @UMLGraph.link
051 */
052@ClassVersion( sourceVersion = "$Id: TriFunction.java 1060 2023-09-24 19:21:40Z tquadrat $" )
053@FunctionalInterface
054@API( status = STABLE, since = "0.0.5" )
055public interface TriFunction<A,B,C,R>
056{
057        /*---------*\
058    ====** Methods **==========================================================
059        \*---------*/
060    /**
061     *  Applies this function to the given arguments.
062     *
063     *  @param  firstArgument   The first function argument.
064     *  @param  secondArgument  The second function argument.
065     *  @param  thirdArgument   The third function argument.
066     *  @return The function result.
067     */
068    public R apply( final A firstArgument, final B secondArgument, final C thirdArgument );
069
070    /**
071     *  Returns a composed function that first applies this function to its
072     *  input, and then applies the after function to the result. If evaluation
073     *  of either function throws an exception, it is relayed to the caller of
074     *  the composed function.
075     *
076     *  @param  <R1>    The type of the output of the {@code after} function,
077     *      and of the composed function.
078     *  @param  after   The function to apply after this function is applied.
079     *  @return A composed function that first applies this function and then
080     *      applies the {@code after} function.
081     *
082     *  @since 0.1.0
083     */
084    @API( status = STABLE, since = "0.1.0" )
085    public default <R1> TriFunction<A,B,C,R1> andThen( final Function<? super R, ? extends R1> after )
086    {
087        final TriFunction<A,B,C,R1> retValue = ( A firstArgument, B secondArgument, C thirdArgument ) -> requireNonNullArgument( after, "after" )
088            .apply( apply( firstArgument, secondArgument, thirdArgument ) );
089
090        //---* Done *----------------------------------------------------------
091        return retValue;
092    }   //  andThem()
093}
094//  class TriFunction
095
096/*
097 *  End of File
098 */