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 org.apiguardian.api.API;
025import org.tquadrat.foundation.annotation.ClassVersion;
026
027/**
028 *  <p>{@summary Represents an operation that accepts three input arguments and
029 *  returns no result.} This is the three-arity specialisation of
030 *  {@link java.util.function.Consumer}.
031 *  Unlike most other functional interfaces, {@code TriConsumer} is expected to
032 *  operate via side effects.</p>
033 *  <p>This is a
034 *  {@linkplain java.lang.FunctionalInterface functional interface}
035 *  whose functional method is
036 *  {@link #accept(Object,Object,Object)}.</p>
037 *
038 *  @param  <A> The type of the first argument to the operation.
039 *  @param  <B> The type of the second argument to the operation.
040 *  @param  <C> The type of the third argument to the operation.
041 *
042 *  @see java.util.function.Consumer
043 *  @see java.util.function.BiConsumer
044 *
045 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
046 *  @version $Id: TriConsumer.java 1060 2023-09-24 19:21:40Z tquadrat $
047 *  @since 0.0.5
048 *
049 *  @UMLGraph.link
050 */
051@ClassVersion( sourceVersion = "$Id: TriConsumer.java 1060 2023-09-24 19:21:40Z tquadrat $" )
052@FunctionalInterface
053@API( status = STABLE, since = "0.0.5" )
054public interface TriConsumer<A,B,C>
055{
056        /*---------*\
057    ====** Methods **==========================================================
058        \*---------*/
059    /**
060     *  Performs this operation on the given arguments.
061     *
062     *  @param  firstInput  The first input argument.
063     *  @param  secondInput The second input argument.
064     *  @param  thirdInput  The third input argument.
065     */
066    public void accept( final A firstInput, final B secondInput, final C thirdInput );
067
068    /**
069     *  <p>{@summary Returns a composed {@code TriConsumer} that performs, in
070     *  sequence, this operation followed by the {@code after} operation.} If
071     *  performing either operation throws an exception, it is relayed to the
072     *  caller of the composed operation. If performing this operation throws
073     *  an exception, the {@code after} operation will not be performed.</p>
074     *  <p>Both {@code TriConsumer}s will be called with the same
075     *  arguments.</p>
076     *
077     *  @param  after   The operation to perform after this operation.
078     *  @return A composed {@code TriConsumer} that performs in sequence this
079     *      operation followed by the {@code after} operation.
080     */
081    public default TriConsumer<A,B,C> andThen( final TriConsumer<? super A,? super B,? super C> after )
082    {
083        requireNonNullArgument( after, "after" );
084
085        final TriConsumer<A,B,C> retValue = ( firstInput, secondInput, thirdInput ) ->
086        {
087            accept( firstInput, secondInput, thirdInput );
088            after.accept( firstInput, secondInput, thirdInput );
089        };
090
091        //---* Done *----------------------------------------------------------
092        return retValue;
093    }   //  andThen()
094}
095//  class TriConsumer
096
097/*
098 *  End of File
099 */