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 four arguments and produces a result. 025 * 026 * <p> 027 * This interface extends the standard Java {@link java.util.function.Function} pattern to support 028 * four-argument functions. It's useful when you need to pass functions with four 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>Four-argument transformations in functional programming patterns 041 * <li>Builder methods that accept four-parameter functions 042 * <li>Stream operations requiring four-argument functions 043 * <li>Callback patterns with four parameters 044 * </ul> 045 * 046 * <h5 class='section'>Usage:</h5> 047 * <p class='bjava'> 048 * <jc>// Lambda expression</jc> 049 * Function4<String,Integer,Boolean,Double,String> <jv>format</jv> = (<jv>s</jv>, <jv>i</jv>, <jv>b</jv>, <jv>d</jv>) -> 050 * <jv>s</jv> + <js>"-"</js> + <jv>i</jv> + <js>"-"</js> + (<jv>b</jv> ? <js>"Y"</js> : <js>"N"</js>) + <js>"-"</js> + <jv>d</jv>; 051 * String <jv>result</jv> = <jv>format</jv>.apply(<js>"prefix"</js>, 42, <jk>true</jk>, 95.5); <jc>// Returns "prefix-42-Y-95.5"</jc> 052 * 053 * <jc>// Function composition</jc> 054 * Function4<Integer,Integer,Integer,Integer,Integer> <jv>add</jv> = (<jv>a</jv>, <jv>b</jv>, <jv>c</jv>, <jv>d</jv>) -> <jv>a</jv> + <jv>b</jv> + <jv>c</jv> + <jv>d</jv>; 055 * Function4<Integer,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, 1); <jc>// Returns "11"</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 Function3} - Three-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 <D> The type of the fourth argument to the function. 070 * @param <R> The type of the result of the function. 071 */ 072@FunctionalInterface 073public interface Function4<A,B,C,D,R> { 074 075 /** 076 * Returns a composed function that first applies this function to its input, and then applies 077 * the {@code after} function to the result. 078 * 079 * <p> 080 * This method enables function composition, allowing you to chain multiple transformations together. 081 * 082 * <h5 class='section'>Example:</h5> 083 * <p class='bjava'> 084 * Function4<Integer,Integer,Integer,Integer,Integer> <jv>multiply</jv> = (<jv>a</jv>, <jv>b</jv>, <jv>c</jv>, <jv>d</jv>) -> <jv>a</jv> * <jv>b</jv> * <jv>c</jv> * <jv>d</jv>; 085 * Function4<Integer,Integer,Integer,Integer,String> <jv>multiplyAndFormat</jv> = <jv>multiply</jv>.andThen(<jv>n</jv> -> <js>"Result: "</js> + <jv>n</jv>); 086 * String <jv>result</jv> = <jv>multiplyAndFormat</jv>.apply(2, 3, 2, 2); <jc>// Returns "Result: 24"</jc> 087 * </p> 088 * 089 * @param <V> The type of output of the {@code after} function, and of the composed function. 090 * @param after The function to apply after this function is applied. Must not be <jk>null</jk>. 091 * @return A composed function that first applies this function and then applies the {@code after} function. 092 * @throws NullPointerException if {@code after} is <jk>null</jk>. 093 */ 094 default <V> Function4<A,B,C,D,V> andThen(Function<? super R,? extends V> after) { 095 assertArgNotNull("after", after); 096 return (A a, B b, C c, D d) -> after.apply(apply(a, b, c, d)); 097 } 098 099 /** 100 * Applies this function to the given arguments. 101 * 102 * <h5 class='section'>Example:</h5> 103 * <p class='bjava'> 104 * Function4<String,Integer,Boolean,Double,String> <jv>format</jv> = (<jv>s</jv>, <jv>n</jv>, <jv>upper</jv>, <jv>mult</jv>) -> { 105 * String <jv>result</jv> = <jv>s</jv>.repeat(<jv>n</jv>); 106 * <jv>result</jv> = <jv>upper</jv> ? <jv>result</jv>.toUpperCase() : <jv>result</jv>; 107 * <jk>return</jk> <jv>result</jv> + <js>" x"</js> + <jv>mult</jv>; 108 * }; 109 * String <jv>result</jv> = <jv>format</jv>.apply(<js>"ha"</js>, 2, <jk>true</jk>, 1.5); <jc>// Returns "HAHA x1.5"</jc> 110 * </p> 111 * 112 * @param a The first function argument. 113 * @param b The second function argument. 114 * @param c The third function argument. 115 * @param d The fourth function argument. 116 * @return The function result. 117 */ 118 R apply(A a, B b, C c, D d); 119}