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 019 020import java.util.function.*; 021import static org.apache.juneau.commons.utils.Shorts.*; 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 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<String,Integer,Boolean,String> <jv>format</jv> = (<jv>s</jv>, <jv>i</jv>, <jv>b</jv>) -> 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<Integer,Integer,Integer,Integer> <jv>add</jv> = (<jv>a</jv>, <jv>b</jv>, <jv>c</jv>) -> <jv>a</jv> + <jv>b</jv> + <jv>c</jv>; 055 * Function3<Integer,Integer,Integer,String> <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/JuneauCommons">juneau-commons</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 072@SuppressWarnings({ 073 "java:S1192" // Duplicated literals (argument/property names) read more clearly inline than as constants 074}) 075public interface Function3<A,B,C,R> { 076 077 /** 078 * Returns a composed function that first applies this function to its input, and then applies 079 * the {@code after} function to the result. 080 * 081 * <p> 082 * This method enables function composition, allowing you to chain multiple transformations together. 083 * 084 * <h5 class='section'>Example:</h5> 085 * <p class='bjava'> 086 * Function3<Integer,Integer,Integer,Integer> <jv>multiply</jv> = (<jv>a</jv>, <jv>b</jv>, <jv>c</jv>) -> <jv>a</jv> * <jv>b</jv> * <jv>c</jv>; 087 * Function3<Integer,Integer,Integer,String> <jv>multiplyAndFormat</jv> = <jv>multiply</jv>.andThen(<jv>n</jv> -> <js>"Result: "</js> + <jv>n</jv>); 088 * String <jv>result</jv> = <jv>multiplyAndFormat</jv>.apply(2, 3, 7); <jc>// Returns "Result: 42"</jc> 089 * </p> 090 * 091 * @param <V> The type of output of the {@code after} function, and of the composed function. 092 * @param after The function to apply after this function is applied. Must not be <jk>null</jk>. 093 * @return A composed function that first applies this function and then applies the {@code after} function. 094 * @throws NullPointerException if {@code after} is <jk>null</jk>. 095 */ 096 default <V> Function3<A,B,C,V> andThen(Function<? super R,? extends V> after) { 097 reqnn("after", after); 098 return (A a, B b, C c) -> after.apply(apply(a, b, c)); 099 } 100 101 /** 102 * Applies this function to the given arguments. 103 * 104 * <h5 class='section'>Example:</h5> 105 * <p class='bjava'> 106 * Function3<String,Integer,Boolean,String> <jv>repeat</jv> = (<jv>s</jv>, <jv>n</jv>, <jv>upper</jv>) -> { 107 * String <jv>result</jv> = <jv>s</jv>.repeat(<jv>n</jv>); 108 * <jk>return</jk> <jv>upper</jv> ? <jv>result</jv>.toUpperCase() : <jv>result</jv>; 109 * }; 110 * String <jv>result</jv> = <jv>repeat</jv>.apply(<js>"ha"</js>, 3, <jk>true</jk>); <jc>// Returns "HAHAHA"</jc> 111 * </p> 112 * 113 * @param a The first function argument. 114 * @param b The second function argument. 115 * @param c The third function argument. 116 * @return The function result. 117 */ 118 R apply(A a, B b, C c); 119}