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 two arguments and produces a result.
025 *
026 * <p>
027 * This interface extends the standard Java {@link java.util.function.Function} pattern to support
028 * two-argument functions. It's useful when you need to pass functions with two 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>Two-argument transformations in functional programming patterns
041 *    <li>Builder methods that accept two-parameter functions
042 *    <li>Stream operations requiring two-argument functions
043 *    <li>Callback patterns with two parameters
044 * </ul>
045 *
046 * <h5 class='section'>Usage:</h5>
047 * <p class='bjava'>
048 *    <jc>// Lambda expression</jc>
049 *    Function2&lt;String,Integer,String&gt; <jv>concat</jv> = (<jv>s</jv>, <jv>i</jv>) -&gt; <jv>s</jv> + <js>"-"</js> + <jv>i</jv>;
050 *    String <jv>result</jv> = <jv>concat</jv>.apply(<js>"prefix"</js>, 42);  <jc>// Returns "prefix-42"</jc>
051 *
052 *    <jc>// Method reference</jc>
053 *    Function2&lt;String,String,Boolean&gt; <jv>equals</jv> = String::equals;
054 *    <jk>boolean</jk> <jv>match</jv> = <jv>equals</jv>.apply(<js>"hello"</js>, <js>"hello"</js>);  <jc>// Returns true</jc>
055 *
056 *    <jc>// Function composition</jc>
057 *    Function2&lt;Integer,Integer,Integer&gt; <jv>add</jv> = (<jv>a</jv>, <jv>b</jv>) -&gt; <jv>a</jv> + <jv>b</jv>;
058 *    Function2&lt;Integer,Integer,String&gt; <jv>addAndFormat</jv> = <jv>add</jv>.andThen(Object::toString);
059 *    String <jv>sum</jv> = <jv>addAndFormat</jv>.apply(5, 3);  <jc>// Returns "8"</jc>
060 * </p>
061 *
062 * <h5 class='section'>See Also:</h5><ul>
063 *    <li class='jc'>{@link Function3} - Three-argument function
064 *    <li class='jc'>{@link Function4} - Four-argument function
065 *    <li class='jc'>{@link Function5} - Five-argument function
066 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauCommonsBasics">juneau-commons Basics</a>
067 * </ul>
068 *
069 * @param <A> The type of the first argument to the function.
070 * @param <B> The type of the second argument to the function.
071 * @param <R> The type of the result of the function.
072 */
073@FunctionalInterface
074public interface Function2<A,B,R> {
075
076   /**
077    * Returns a composed function that first applies this function to its input, and then applies
078    * the {@code after} function to the result.
079    *
080    * <p>
081    * This method enables function composition, allowing you to chain multiple transformations together.
082    *
083    * <h5 class='section'>Example:</h5>
084    * <p class='bjava'>
085    *    Function2&lt;Integer,Integer,Integer&gt; <jv>multiply</jv> = (<jv>a</jv>, <jv>b</jv>) -&gt; <jv>a</jv> * <jv>b</jv>;
086    *    Function2&lt;Integer,Integer,String&gt; <jv>multiplyAndFormat</jv> = <jv>multiply</jv>.andThen(<jv>n</jv> -&gt; <js>"Result: "</js> + <jv>n</jv>);
087    *    String <jv>result</jv> = <jv>multiplyAndFormat</jv>.apply(6, 7);  <jc>// Returns "Result: 42"</jc>
088    * </p>
089    *
090    * @param <V> The type of output of the {@code after} function, and of the composed function.
091    * @param after The function to apply after this function is applied. Must not be <jk>null</jk>.
092    * @return A composed function that first applies this function and then applies the {@code after} function.
093    * @throws NullPointerException if {@code after} is <jk>null</jk>.
094    */
095   default <V> Function2<A,B,V> andThen(Function<? super R,? extends V> after) {
096      assertArgNotNull("after", after);
097      return (A a, B b) -> after.apply(apply(a, b));
098   }
099
100   /**
101    * Applies this function to the given arguments.
102    *
103    * <h5 class='section'>Example:</h5>
104    * <p class='bjava'>
105    *    Function2&lt;String,Integer,String&gt; <jv>repeat</jv> = (<jv>s</jv>, <jv>n</jv>) -&gt; <jv>s</jv>.repeat(<jv>n</jv>);
106    *    String <jv>result</jv> = <jv>repeat</jv>.apply(<js>"ha"</js>, 3);  <jc>// Returns "hahaha"</jc>
107    * </p>
108    *
109    * @param a The first function argument.
110    * @param b The second function argument.
111    * @return The function result.
112    */
113   R apply(A a, B b);
114}