org.tinyj.lava.LavaFunction Maven / Gradle / Ivy

package org.tinyj.lava;

/**
 * A function maps its argument to a result. This is the exception declaring version of
 * Java's [`Function`](https://docs.oracle.com/javase/8/docs/api/java/util/function/Function.html)
 *
 * While not strictly required it usually is expected that subsequent
 * invocations with the same argument yield equal results.
 *
 * This is a functional interface whose functional method is `checkedApply(X)`.
 *
 * @param  the function's argument type
 * @param  the function's result type
 * @param  upper limit of thrown exception types
 */
@FunctionalInterface
public interface LavaFunction {

  /**
   * Apply the function to an argument
   *
   * @param x argument to map
   * @return the function's result
   */
  R checkedApply(X x) throws E;

  /**
   * Safely casts between different (#LavaFunction) parametrization
   *
   * @param  accepted argument type
   * @param  required result type
   * @param  required exception limit
   * @param function function to adopt
   * @return `function` casted to the compatible parametrization (#LavaFunction)``
   */
  @SuppressWarnings("unchecked")
  static 
  LavaFunction castDown(LavaFunction function) {
    return (LavaFunction) function;
  }
}