Add Function compose, fix javadocs

src/main/java/com/annimon/stream/Stream.java

@@ -370,7 +370,7 @@ protected void nextIteration() {
      * @param <R> the type of elements in resulting stream
      * @param stream1  the first stream
      * @param stream2  the second stream
-     * @param combiner the combiner function used to apply to each element
+     * @param combiner  the combiner function used to apply to each element
      * @return the new stream
      */
     public static <F, S, R> Stream<R> zip(Stream<? extends F> stream1, Stream<? extends S> stream2, final BiFunction<? super F, ? super S, ? extends R> combiner) {
@@ -678,11 +678,11 @@ public <K> Stream<Map.Entry<K, List<T>>> groupBy(final Function<? super T, ? ext
      * Because of this assumption, it does not need to first collect all elements and then partition them.
      * Instead, it can emit a {@code List} of elements when it reaches the first element that does not
      * belong to the same chunk as the previous elements.
-     * <p>
+     *
      * <p>This is an intermediate operation.
      *
      * @param <K> the type of the keys, which are the result of the classifier function
-     * @param classifier the classifier function
+     * @param classifier  the classifier function
      * @return the new stream
      */
     public <K> Stream<List<T>> chunkBy(final Function<? super T, ? extends K> classifier) {
@@ -726,10 +726,10 @@ private T peek() {
 
     /**
      * Samples the {@code Stream} by emitting every n-th element.
-     * <p>
+     *
      * <p>This is an intermediate operation.
      *
-     * @param stepWidth step width
+     * @param stepWidth  step width
      * @return the new stream
      */
     public Stream<T> sample(final int stepWidth) {
@@ -744,10 +744,11 @@ public T apply(List<T> list) {
     /**
      * Partitions {@code Stream} into {@code List}s of fixed size by sliding over the elements of the stream.
      * It starts with the first element and in each iteration moves by 1. This method yields the same results
-     * as calling {@link #slidingWindow(int, int)} with a {@code stepWidth} of 1. <p> <p>This is an
-     * intermediate operation.
+     * as calling {@link #slidingWindow(int, int)} with a {@code stepWidth} of 1.
      *
-     * @param windowSize number of elements that will be emitted together in a list
+     * <p>This is an intermediate operation.
+     *
+     * @param windowSize  number of elements that will be emitted together in a list
      * @return the new stream
      * @see #slidingWindow(int, int)
      */
@@ -761,9 +762,9 @@ public Stream<List<T>> slidingWindow(final int windowSize) {
      * allows, for example, to partition the elements into batches of {@code windowSize} elements (by using a
      * step width equal to the specified window size) or to sample every n-th element (by using a window size
      * of 1 and a step width of n).
-     * <p>
+     *
      * <p>This is an intermediate operation.
-     * <p>
+     *
      * <p>Examples: <pre>
      * elements: [1, 1, 1, 2, 2, 2, 3, 3, 3]    windowSize: 3   stepWidth: 3
      *
@@ -780,7 +781,7 @@ public Stream<List<T>> slidingWindow(final int windowSize) {
      * =&gt; [1, 2, 3], [2, 3, 4], [3, 4, 5], [4, 5, 6]
      * </pre>
      *
-     * @param windowSize number of elements that will be emitted together in a list
+     * @param windowSize  number of elements that will be emitted together in a list
      * @param stepWidth  step width
      * @return the new stream
      */

src/main/java/com/annimon/stream/function/BiConsumer.java

@@ -2,31 +2,31 @@
 
 /**
  * Represents an operation on two input arguments.
- * 
+ *
  * @param <T> the type of the first argument
  * @param <U> the type of the second argument
  * @see Consumer
  */
 @FunctionalInterface
 public interface BiConsumer<T, U> {
-    
+
     /**
      * Performs operation on two arguments.
-     * 
+     *
      * @param value1  the first argument
      * @param value2  the second argument
      */
     void accept(T value1, U value2);
-    
+
     class Util {
-        
+
         private Util() { }
-        
+
         /**
-         * Compose {@code BiConsumer} calls.
-         * 
+         * Composes {@code BiConsumer} calls.
+         *
          * <p>{@code c1.accept(t, u); c2.accept(t, u); }
-         * 
+         *
          * @param <T> the type of the first argument
          * @param <U> the type of the second argument
          * @param c1  the first {@code BiConsumer}

src/main/java/com/annimon/stream/function/BiFunction.java

@@ -2,32 +2,32 @@
 
 /**
  * Represents a function which produces result from two input arguments.
- * 
+ *
  * @param <T> the type of the first argument
  * @param <U> the type of the second argument
  * @param <R> the type of the result of the function
  */
 @FunctionalInterface
 public interface BiFunction<T, U, R> {
-    
+
     /**
      * Applies this function to the given arguments.
-     * 
+     *
      * @param value1  the first argument
      * @param value2  the second argument
      * @return the function result
      */
     R apply(T value1, U value2);
-    
+
     class Util {
-        
+
         private Util() { }
-        
+
         /**
-         * Compose {@code BiFunction} calls.
-         * 
+         * Composes {@code BiFunction} calls.
+         *
          * <p>{@code f2.apply(f1.apply(t, u)) }
-         * 
+         *
          * @param <T> the type of the first argument
          * @param <U> the type of the second argument
          * @param <R> the type of the result of the {@code BiFunction f1}

src/main/java/com/annimon/stream/function/BinaryOperator.java

@@ -12,9 +12,9 @@
 @FunctionalInterface
 public interface BinaryOperator<T> extends BiFunction<T, T, T> {
     class Util {
-        
+
         private Util() { }
-        
+
         /**
          * Returns a {@code BinaryOperator} which returns lesser of two elements
          * according to the specified {@code Comparator}.

src/main/java/com/annimon/stream/function/Consumer.java

@@ -2,29 +2,29 @@
 
 /**
  * Represents an operation on input argument.
- * 
+ *
  * @param <T> the type of the input to the operation
  * @see BiConsumer
  */
 @FunctionalInterface
 public interface Consumer<T> {
-    
+
     /**
      * Performs operation on argument.
-     * 
+     *
      * @param value  the input argument
      */
     void accept(T value);
-    
+
     class Util {
-        
+
         private Util() { }
-        
+
         /**
-         * Compose {@code Consumer} calls.
-         * 
+         * Composes {@code Consumer} calls.
+         *
          * <p>{@code c1.accept(value); c2.accept(value); }
-         * 
+         *
          * @param <T> the type of the input to the operation
          * @param c1  the first {@code Consumer}
          * @param c2  the second {@code Consumer}

src/main/java/com/annimon/stream/function/Function.java

@@ -2,37 +2,58 @@
 
 /**
  * Represents a function which produces result from input arguments.
- * 
+ *
  * @param <T> the type of the input of the function
  * @param <R> the type of the result of the function
  */
 @FunctionalInterface
 public interface Function<T, R> {
-    
+
     /**
      * Applies this function to the given argument.
-     * 
+     *
      * @param value  an argument
      * @return the function result
      */
     R apply(T value);
-    
+
     class Util {
-        
+
         private Util() { }
-
+
+        /**
+         * Composes {@code Function} calls.
+         *
+         * <p>{@code f1.apply(f2.apply(v)) }
+         *
+         * @param <V> the type of the input argument of first function
+         * @param <T> the type of the result of {@code f2} and input argument of {@code f1}
+         * @param <R> the type of the result of composed function {@code f1}
+         * @param f1  the function for transform {@code Function f2} result to the type {@code R}
+         * @param f2  the {@code Function} which is called first
+         * @return the result of composed function
+         * @throws NullPointerException if {@code f1} or {@code f2} or result of {@code Function f1} is null
+         * @see #andThen(com.annimon.stream.function.Function, com.annimon.stream.function.Function)
+         */
+        public static <V, T, R> Function<V, R> compose(
+                final Function<? super T, ? extends R> f1,
+                final Function<? super V, ? extends T> f2) {
+            return Util.<V, T, R>andThen(f2, f1);
+        }
+
         /**
-         * Compose {@code Function} calls.
-         * 
+         * Composes {@code Function} calls.
+         *
          * <p>{@code f2.apply(f1.apply(t)) }
-         * 
+         *
          * @param <T> the type of the input argument of first function
          * @param <R> the type of the result of {@code f1} and input argument of {@code f2}
          * @param <V> the type of the result of composed function {@code f2}
          * @param f1  the {@code Function} which is called first
          * @param f2  the function for transform {@code Function f1} result to the type {@code V}
          * @return the result of composed function
          * @throws NullPointerException if {@code f1} or {@code f2} or result of {@code Function f1} is null
+         * @see #compose(com.annimon.stream.function.Function, com.annimon.stream.function.Function)
          */
         public static <T, R, V> Function<T, V> andThen(
                 final Function<? super T, ? extends R> f1,

src/main/java/com/annimon/stream/function/Predicate.java

@@ -2,27 +2,27 @@
 
 /**
  * Represents a predicate, i.e. function with boolean type result.
- * 
+ *
  * @param <T> the type of the input to the function
  */
 @FunctionalInterface
 public interface Predicate<T> {
-    
+
     /**
      * Tests the value for satisfying predicate.
-     * 
+     *
      * @param value  the value to be tests
      * @return {@code true} if the value matches the predicate, otherwise {@code false}
      */
     boolean test(T value);
-    
+
     class Util {
-        
+
         private Util() { }
-        
+
         /**
-         * Apply logical AND to predicates.
-         * 
+         * Applies logical AND to predicates.
+         *
          * @param <T> the type of the input to the function
          * @param p1  the first predicate
          * @param p2  the second predicate
@@ -39,8 +39,8 @@ public boolean test(T value) {
         }
 
         /**
-         * Apply logical OR to predicates.
-         * 
+         * Applies logical OR to predicates.
+         *
          * @param <T> the type of the input to the function
          * @param p1  the first predicate
          * @param p2  the second predicate
@@ -55,10 +55,10 @@ public boolean test(T value) {
                 }
             };
         }
-        
+
         /**
-         * Apply logical XOR to predicates.
-         * 
+         * Applies logical XOR to predicates.
+         *
          * @param <T> the type of the input to the function
          * @param p1  the first predicate
          * @param p2  the second predicate
@@ -75,8 +75,8 @@ public boolean test(T value) {
         }
 
         /**
-         * Apply logical negation to predicate.
-         * 
+         * Applies logical negation to predicate.
+         *
          * @param <T> the type of the input to the function
          * @param p1  the predicate to be negated
          * @return a composed {@code Predicate}

src/main/java/com/annimon/stream/function/Supplier.java

@@ -2,15 +2,15 @@
 
 /**
  * Represents a function which supply a result.
- * 
+ *
  * @param <T> the type of the result
  */
 @FunctionalInterface
 public interface Supplier<T> {
-    
+
     /**
      * Gets a result.
-     * 
+     *
      * @return a result
      */
     T get();

src/main/java/com/annimon/stream/function/ThrowableSupplier.java

@@ -2,16 +2,16 @@
 
 /**
  * Represents a function for supplying result which can throw an exception.
- * 
+ *
  * @param <T> the type of the result
  * @param <E> the type of the exception
  */
 @FunctionalInterface
 public interface ThrowableSupplier<T, E extends Throwable> {
-    
+
     /**
      * Gets a result.
-     * 
+     *
      * @return a result
      * @throws E an exception
      */

src/main/java/com/annimon/stream/function/UnaryOperator.java

@@ -9,9 +9,9 @@
 @FunctionalInterface
 public interface UnaryOperator<T> extends Function<T, T> {
     class Util {
-        
+
         private Util() { }
-        
+
         /**
          * Returns a unary operator that always returns its input argument.
          *