001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
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,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.function;
018
019import static org.apache.juneau.commons.utils.AssertionUtils.*;
020
021import java.util.function.*;
022
023/**
024 * A functional interface representing a function that accepts three arguments and produces a result.
025 *
026 * <p>
027 * This interface extends the standard Java {@link java.util.function.Function} pattern to support
028 * three-argument functions. It's useful when you need to pass functions with three parameters to methods
029 * that expect functional interfaces, such as in stream operations, builders, or callback patterns.
030 *
031 * <h5 class='section'>Features:</h5>
032 * <ul class='spaced-list'>
033 *    <li>Functional interface - can be used with lambda expressions and method references
034 *    <li>Composition support - provides {@link #andThen(Function)} for function chaining
035 *    <li>Type-safe - generic type parameters ensure compile-time type safety
036 * </ul>
037 *
038 * <h5 class='section'>Use Cases:</h5>
039 * <ul class='spaced-list'>
040 *    <li>Three-argument transformations in functional programming patterns
041 *    <li>Builder methods that accept three-parameter functions
042 *    <li>Stream operations requiring three-argument functions
043 *    <li>Callback patterns with three parameters
044 * </ul>
045 *
046 * <h5 class='section'>Usage:</h5>
047 * <p class='bjava'>
048 *    <jc>// Lambda expression</jc>
049 *    Function3&lt;String,Integer,Boolean,String&gt; <jv>format</jv> = (<jv>s</jv>, <jv>i</jv>, <jv>b</jv>) -&gt;
050 *       <jv>s</jv> + <js>"-"</js> + <jv>i</jv> + <js>"-"</js> + (<jv>b</jv> ? <js>"Y"</js> : <js>"N"</js>);
051 *    String <jv>result</jv> = <jv>format</jv>.apply(<js>"prefix"</js>, 42, <jk>true</jk>);  <jc>// Returns "prefix-42-Y"</jc>
052 *
053 *    <jc>// Function composition</jc>
054 *    Function3&lt;Integer,Integer,Integer,Integer&gt; <jv>add</jv> = (<jv>a</jv>, <jv>b</jv>, <jv>c</jv>) -&gt; <jv>a</jv> + <jv>b</jv> + <jv>c</jv>;
055 *    Function3&lt;Integer,Integer,Integer,String&gt; <jv>addAndFormat</jv> = <jv>add</jv>.andThen(Object::toString);
056 *    String <jv>sum</jv> = <jv>addAndFormat</jv>.apply(5, 3, 2);  <jc>// Returns "10"</jc>
057 * </p>
058 *
059 * <h5 class='section'>See Also:</h5><ul>
060 *    <li class='jc'>{@link Function2} - Two-argument function
061 *    <li class='jc'>{@link Function4} - Four-argument function
062 *    <li class='jc'>{@link Function5} - Five-argument function
063 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauCommonsBasics">juneau-commons Basics</a>
064 * </ul>
065 *
066 * @param <A> The type of the first argument to the function.
067 * @param <B> The type of the second argument to the function.
068 * @param <C> The type of the third argument to the function.
069 * @param <R> The type of the result of the function.
070 */
071@FunctionalInterface
072public interface Function3<A,B,C,R> {
073
074   /**
075    * Returns a composed function that first applies this function to its input, and then applies
076    * the {@code after} function to the result.
077    *
078    * <p>
079    * This method enables function composition, allowing you to chain multiple transformations together.
080    *
081    * <h5 class='section'>Example:</h5>
082    * <p class='bjava'>
083    *    Function3&lt;Integer,Integer,Integer,Integer&gt; <jv>multiply</jv> = (<jv>a</jv>, <jv>b</jv>, <jv>c</jv>) -&gt; <jv>a</jv> * <jv>b</jv> * <jv>c</jv>;
084    *    Function3&lt;Integer,Integer,Integer,String&gt; <jv>multiplyAndFormat</jv> = <jv>multiply</jv>.andThen(<jv>n</jv> -&gt; <js>"Result: "</js> + <jv>n</jv>);
085    *    String <jv>result</jv> = <jv>multiplyAndFormat</jv>.apply(2, 3, 7);  <jc>// Returns "Result: 42"</jc>
086    * </p>
087    *
088    * @param <V> The type of output of the {@code after} function, and of the composed function.
089    * @param after The function to apply after this function is applied. Must not be <jk>null</jk>.
090    * @return A composed function that first applies this function and then applies the {@code after} function.
091    * @throws NullPointerException if {@code after} is <jk>null</jk>.
092    */
093   default <V> Function3<A,B,C,V> andThen(Function<? super R,? extends V> after) {
094      assertArgNotNull("after", after);
095      return (A a, B b, C c) -> after.apply(apply(a, b, c));
096   }
097
098   /**
099    * Applies this function to the given arguments.
100    *
101    * <h5 class='section'>Example:</h5>
102    * <p class='bjava'>
103    *    Function3&lt;String,Integer,Boolean,String&gt; <jv>repeat</jv> = (<jv>s</jv>, <jv>n</jv>, <jv>upper</jv>) -&gt; {
104    *       String <jv>result</jv> = <jv>s</jv>.repeat(<jv>n</jv>);
105    *       <jk>return</jk> <jv>upper</jv> ? <jv>result</jv>.toUpperCase() : <jv>result</jv>;
106    *    };
107    *    String <jv>result</jv> = <jv>repeat</jv>.apply(<js>"ha"</js>, 3, <jk>true</jk>);  <jc>// Returns "HAHAHA"</jc>
108    * </p>
109    *
110    * @param a The first function argument.
111    * @param b The second function argument.
112    * @param c The third function argument.
113    * @return The function result.
114    */
115   R apply(A a, B b, C c);
116}