net.sf.staccatocommons.defs.function.Function2 Maven / Gradle / Ivy

Go to download
/**
 *  Copyright (c) 2010-2012, The StaccatoCommons Team
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU Lesser General Public License as published by
 *  the Free Software Foundation; version 3 of the License.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 */


package net.sf.staccatocommons.defs.function;

import net.sf.staccatocommons.defs.Applicable;
import net.sf.staccatocommons.defs.Applicable2;
import net.sf.staccatocommons.defs.Applicative;
import net.sf.staccatocommons.defs.Delayable2;
import net.sf.staccatocommons.defs.NullSafe;
import net.sf.staccatocommons.defs.partial.NullSafeAware;
import net.sf.staccatocommons.defs.tuple.Tuple2;
import net.sf.staccatocommons.restrictions.check.NonNull;

/**
 * {@link Function2}s are rich interfaced {@link Applicable2}s - two arguments
 * {@link Delayable2} and {@link NullSafeAware} transformations.
 * 
 * 
 * {@link Function2} can also be partially
 * applied, which means, applying it with less arguments than required,
 * returning, instead of the result of the transformation, a new function that
 * expects the rest of the arguments. Thus, {@link Function2} do also implement
 * {@link Applicable}
 * 
 * @author flbulgarelli
 * 
 * @param 
 *          function first argument type
 * @param 
 *          function second argument type
 * @param 
 *          function return type
 * 
 */
@Applicative
public interface Function2 extends Applicable2, Applicable>, Delayable2,
  NullSafeAware> {

  /**
   * Partially applies the function passing just its first parameter
   */
  Function apply(final A arg0);

  /**
   * Applies the function
   */
  C apply(A arg0, B arg1);

  /**
   * Inverts function parameters order
   * 
   * @return a new {@link Function2} that produces the same result of this one
   *         when applied, but with arguments flipped
   */
  Function2 flip();

  /**
   * Answers a new function that returns null if any of its arguments is null,
   * or the result of applying this function, otherwise.
   * 
   * @return a new null-safe {@link Function2}
   */
  @NullSafe
  Function2 nullSafe();

  /**
   * 
   * @param 
   * @param function
   * @return
   * @since 1.2
   */
   Function2 of(Applicable function);

  /**
   * Function composition, like {@link Function#of(Applicable2)}, but with
   * receptor and argument interchanged. Equivalent to {@code other.of(this)}
   * 
   * Functions get combined in the following figure:
   * 
   *    * >----+
   *      +--this---+---other---->
   * >----+
   * 
   * 
   * @param 
   * @param other
   * @return a new {@link Function2}
   * @since 1.2
   */
   Function2 then(@NonNull Function other);

  /**
   * Answers a three arg function that combines this function with
   * other function, using a binaryFunction to merge
   * the results.
   * 
   * The answered {@link Function2} will apply this function to its first and
   * second argument argument, other function to the third
   * argument, and return the application of binaryFunction to both
   * resulting values.
   * 
   * Functions get combined in the following figure:
   * 
   *    * >----+
   *      +--this-+
   * >----+       +---binaryFunction---->
   *              |
   * >--other-----+
   * 
   * 
   * @param 
   * @param 
   * @param 
   * @param binayFunction
   * @param other
   * @return a new {@link Function3} the merges {@code this} and {@code other}
   *         using the {@code binaryFunciton}
   * @since 1.2
   */
   Function3 then(Function2 binaryFunction,
    @NonNull Function other);
  
  
  /**
   * Uncurries this function,
   * by returning a {@link Function} that takes a
   * single pair, being its components each of the original function parameters
   * 
   * @return a new {@link Function}
   */
  Function, C> uncurry();

}