Package eu.bandm.tools.util.java

Class Functions

java.lang.Object
eu.bandm.tools.util.java.Functions
public abstract class Functions extends Object
Library of constants and operations working with functions.

Most methods of this class implement constructs that can also be expressed with lambda expressions. However, lambda expressions have two downsides:

  • Every lambda expression requires parameter names that are not already taken, polluting the local variable name space.
  • When a reference to a function object is captured for later delegation, it is not checked for null right away; a NullPointerException may arise later and in a remote context.

Therefore, the operations in this class provide means for point-free and fail-fast function-level programming.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static <A, B> Function<A,B>
    adjust(Function<? super A,? extends B> f)
    Returns an equivalent function with different argument and result types.
    static <A> A
    applyAll(A start, Iterable<? extends UnaryOperator<A>> ops)
    Applies a sequence of unary operators in sequence to a start value.
    static <A> A
    applyAll(A start, UnaryOperator<A>... ops)
    Applies a sequence of unary operators in sequence to a start value.
    static <A, B, C> BiFunction<A,B,C>
    binConstant(C result)
    Returns a constant binary function.
    static <A, B, C, D>
    BiFunction<A,B,D>
    compose(BiFunction<? super A,? super B,? extends C> f, Function<? super C,? extends D> g)
    Returns a binary function that applies two given functions in sequence.
    static <A, B, C, D, E>
    BiFunction<A,C,E>
    compose(Function<? super A,? extends B> f, Function<? super C,? extends D> g, BiFunction<? super B,? super D,? extends E> h)
    Returns a binary function that applies three given functions in sequence.
    static <A, B> Function<A,B>
    constant(B result)
    Returns a constant function.
    static <A, B, C> Function<A,Function<B,C>>
    curry(BiFunction<A,B,C> f)
    Returns a function that takes one argument of a binary function instantly, and one later.
    static <A, B> Function<A,B>
    defaultTo(B def, Function<? super A,? extends B> fun)
    Returns a function that substitutes a default value if a given function returns null.
    static <A, B> Predicate<A>
    domain(Function<? super A,? extends B> fun)
    Returns a predicate that checks whether a function returns null for an argument.
    static <A, B> Function<A,B>
    fail()
    Returns a function that always returns null.
    static <A, B, C> BiFunction<B,A,C>
    flip(BiFunction<A,B,C> f)
    Returns a binary function that calls another binary with the arguments flipped.
    static <A, B, C> Function<A,C>
    leftSection(BiFunction<? super A,? super B,? extends C> f, B b)
    Returns a function that calls a binary function with a fixed second argument.
    static <A, B, C> eu.bandm.tools.util.java.Functions.MemoizedBiFunction<A,B,C>
    memoize(BiFunction<A,B,C> fun)
    Returns a binary function that remembers its computed values indefinitely.
    static <A, B> Function<A,B>
    memoize(Function<A,B> fun)
    Returns a unary function that remembers its computed values indefinitely.
    static <A> BinaryOperator<A>
    merge()
    Returns a binary function that returns one of its arguments if they are equal.
    static <A, B> Function<A,B>
    override(Function<? super A,? extends B> first, Function<? super A,? extends B> second)
    Returns a function that tries two given functions in sequence, preferring the first if its result is non-null.
    static <A, B> Function<A,B>
    restrict(Function<? super A,? extends B> fun, Predicate<? super A> cond)
    Returns a function that applies a given function only if a precondition is satisfied.
    static <A, B, C> Function<B,C>
    rightSection(BiFunction<? super A,? super B,? extends C> f, A a)
    Returns a function that calls a binary function with a fixed first argument.
    static <A, B> Function<A,B>
    strict(Function<A,B> fun)
    Returns a function that applies a given function only if the argument is non-null.
    static <A> Function<A,A>
    trace(PrintStream out, String label)
    Returns a function that returns its argument, and prints it as a side-effect.
    static <A> Function<A,A>
    trace(String label)
    Returns a function that returns its argument, and prints it as a side-effect.
    static <A, B, C> BiFunction<A,B,C>
    uncurry(Function<A,? extends Function<B,C>> f)
    Returns a binary function that applies its first argument to a unary function-valued function, and its second to the result.
    static <A, B> Function<A,B>
    undef(String n)
    Returns a function that is undefined for all arguments.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • undef

      public static <A, B> Function<A,B> undef(String n)
      Returns a function that is undefined for all arguments.
      Type Parameters:
      A - the value type
      B - the result type
      Parameters:
      n - a descriptive name for the function
      Returns:
      a function that throws IllegalArgumentException for any argument

    • curry

      public static <A, B, C> Function<A,Function<B,C>> curry(BiFunction<A,B,C> f)
      Returns a function that takes one argument of a binary function instantly, and one later.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given function is null.

      Type Parameters:
      A - the first argument type
      B - the second argument type
      C - the result type
      Parameters:
      f - a binary function
      Returns:
      a function that, when applied to a, returns a function that, when applied to b, calls f with the pair (a, b)
      Throws:
      NullPointerException - if f is null

    • uncurry

      public static <A, B, C> BiFunction<A,B,C> uncurry(Function<A,? extends Function<B,C>> f)
      Returns a binary function that applies its first argument to a unary function-valued function, and its second to the result.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given function is null.

      Type Parameters:
      A - the first argument type
      B - the second argument type
      C - the result type
      Parameters:
      f - a unary function-valued function
      Returns:
      a function that, when applied to (a, b), applies f to a and the resulting intermediate function to b
      Throws:
      NullPointerException - if f is null

    • constant

      public static <A, B> Function<A,B> constant(B result)
      Returns a constant function.

      This method may be preferrable to a lambda expression in some contexts, because no parameter has to be introduced.

      Type Parameters:
      A - the type of arguments
      B - the type of results
      Parameters:
      result - the specified result
      Returns:
      a function that just returns result for any argument

    • binConstant

      public static <A, B, C> BiFunction<A,B,C> binConstant(C result)
      Returns a constant binary function.

      This method may be preferrable to a lambda expression in some contexts, because no parameters have to be introduced.

      Type Parameters:
      A - the first argument type
      B - the second argument type
      C - the result type
      Parameters:
      result - the specified result
      Returns:
      a binary function that returns result for any arguments

    • flip

      public static <A, B, C> BiFunction<B,A,C> flip(BiFunction<A,B,C> f)
      Returns a binary function that calls another binary with the arguments flipped.
      Type Parameters:
      A - the first argument type (of the given function)
      B - the second argument type (of the given function)
      C - the result type
      Parameters:
      f - a binary function
      Returns:
      a function that, when called with (b, a) calls f with (a, b)

    • rightSection

      public static <A, B, C> Function<B,C> rightSection(BiFunction<? super A,? super B,? extends C> f, A a)
      Returns a function that calls a binary function with a fixed first argument.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given function is null.

      Type Parameters:
      A - the first argument type
      B - the second argument type
      C - the result type
      Parameters:
      f - a binary function
      a - the fixed first argument
      Returns:
      a function that, when applied to b, applies f to the pair (a, b)
      Throws:
      NullPointerException - if f is null

    • leftSection

      public static <A, B, C> Function<A,C> leftSection(BiFunction<? super A,? super B,? extends C> f, B b)
      Returns a function that calls a binary function with a fixed second argument.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given function is null.

      Type Parameters:
      A - the first argument type
      B - the second argument type
      C - the result type
      Parameters:
      f - a binary function
      b - the fixed second argument
      Returns:
      a function that, when applied to a, applies f to the pair (a, b)
      Throws:
      NullPointerException - if f is null

    • compose

      public static <A, B, C, D> BiFunction<A,B,D> compose(BiFunction<? super A,? super B,? extends C> f, Function<? super C,? extends D> g)
      Returns a binary function that applies two given functions in sequence.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given functions are null.

      Type Parameters:
      A - the first argument type
      B - the second argument type
      C - the type of intermediate values
      D - the type of results
      Parameters:
      f - the binary function to apply first
      g - the function to apply second
      Returns:
      a function that applies inner followed by outer to its arguments
      Throws:
      NullPointerException - if f or g is null

    • compose

      public static <A, B, C, D, E> BiFunction<A,C,E> compose(Function<? super A,? extends B> f, Function<? super C,? extends D> g, BiFunction<? super B,? super D,? extends E> h)
      Returns a binary function that applies three given functions in sequence.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given functions are null.

      Type Parameters:
      A - the first argument type
      B - the first intermediate value type
      C - the second argument type
      D - the second intermediate value type
      E - the type of results
      Parameters:
      f - the function to apply to first arguments
      g - the function to apply to second arguments
      h - the binary function to apply after both
      Returns:
      a function that applies f and g in unspecified order to its arguments, and h on the pair of results
      Throws:
      NullPointerException - if f or g or h is null

    • fail

      public static <A, B> Function<A,B> fail()
      Returns a function that always returns null.
      Type Parameters:
      A - the type of arguments
      B - the thype of results
      Returns:
      a function that returns null for any argument

    • restrict

      public static <A, B> Function<A,B> restrict(Function<? super A,? extends B> fun, Predicate<? super A> cond)
      Returns a function that applies a given function only if a precondition is satisfied.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given functions are null.

      Type Parameters:
      A - the argument type
      B - the result type
      Parameters:
      fun - a function to call conditionally
      cond - a predicate specifying a precondition
      Returns:
      a function that, when called with a, calls f if cond returns true, or returns null without calling f otherwise
      Throws:
      NullPointerException - if fun or cond is null

    • strict

      public static <A, B> Function<A,B> strict(Function<A,B> fun)
      Returns a function that applies a given function only if the argument is non-null.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given function is null.

      Type Parameters:
      A - the argument type
      B - the result type
      Parameters:
      fun - a function to call conditionally
      Returns:
      a function that, when called with non-null a, calls f, or just returns null otherwise
      Throws:
      NullPointerException - if fun is null

    • override

      public static <A, B> Function<A,B> override(Function<? super A,? extends B> first, Function<? super A,? extends B> second)
      Returns a function that tries two given functions in sequence, preferring the first if its result is non-null.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given functions are null.

      Type Parameters:
      A - the argument type
      B - the result type
      Parameters:
      first - the first function to try
      second - the second function to try
      Returns:
      a function that calls first and returns the result if non-zero; otherwise second is called with the same argument.
      Throws:
      NullPointerException - if first or second is null

    • defaultTo

      public static <A, B> Function<A,B> defaultTo(B def, Function<? super A,? extends B> fun)
      Returns a function that substitutes a default value if a given function returns null.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given function is null.

      Type Parameters:
      A - the type of arguments
      B - the type of results
      Parameters:
      def - the specified default value
      fun - a function
      Returns:
      the result of fun if non-null; the default value otherwise
      Throws:
      NullPointerException - if fun is null

    • domain

      public static <A, B> Predicate<A> domain(Function<? super A,? extends B> fun)
      Returns a predicate that checks whether a function returns null for an argument.

      This method may be preferrable to a lambda expression in some contexts, because it fails immediately if the given function is null.

      Type Parameters:
      A - the type of arguments
      B - the type of results
      Parameters:
      fun - a function
      Returns:
      a predicate that returns true if and only if fun returns a non-null value for the same argument
      Throws:
      NullPointerException - if fun is null

    • adjust

      public static <A, B> Function<A,B> adjust(Function<? super A,? extends B> f)
      Returns an equivalent function with different argument and result types.
      Type Parameters:
      A - the desired argument type
      B - the desired result type
      Parameters:
      f - the function
      Returns:
      an equivalent function, but possibly with a more restricted argument type and/or a more general result type

    • trace

      public static <A> Function<A,A> trace(String label)
      Returns a function that returns its argument, and prints it as a side-effect.
      Type Parameters:
      A - the value type
      Parameters:
      label - a label for printing
      Returns:
      a function that returns its argument after printing it, prefixed with label, to System.err

    • trace

      public static <A> Function<A,A> trace(PrintStream out, String label)
      Returns a function that returns its argument, and prints it as a side-effect.
      Type Parameters:
      A - the value type
      Parameters:
      out - an output stream
      label - a label for printing
      Returns:
      a function that returns its argument after printing it, prefixed with label, to out

    • memoize

      public static <A, B> Function<A,B> memoize(Function<A,B> fun)
      Returns a unary function that remembers its computed values indefinitely.

      Instead of computing the result for the same argument (up to Object.equals(java.lang.Object)) twice, the previous result is stored and retrieved.

      Behavior is unspecified for functions that are not both stateless and deterministic.

      Storage of values may create a space leak; make sure to dispose of (all references to) the memoized function when no longer needed.

      Type Parameters:
      A - the argument type
      B - the result type
      Parameters:
      fun - binary function
      Returns:
      a function that computes the same values, but only once
      Throws:
      NullPointerException - if fun is null

    • memoize

      public static <A, B, C> eu.bandm.tools.util.java.Functions.MemoizedBiFunction<A,B,C> memoize(BiFunction<A,B,C> fun)
      Returns a binary function that remembers its computed values indefinitely.

      Instead of computing the result for the same pair of arguments (up to Object.equals(java.lang.Object)) twice, the previous result is stored and retrieved.

      Behavior is unspecified for functions that are not both stateless and deterministic.

      Storage of values may create a space leak; make sure to dispose of (all references to) the memoized function when no longer needed.

      Type Parameters:
      A - the first argument type
      B - the second argument type
      C - the result type
      Parameters:
      fun - a binary function
      Returns:
      a binary function that computes the same values, but only once
      Throws:
      NullPointerException - if fun is null

    • applyAll

      @SafeVarargs public static <A> A applyAll(A start, UnaryOperator<A>... ops)
      Applies a sequence of unary operators in sequence to a start value.
      Type Parameters:
      A - the type of values
      Parameters:
      start - the start value
      ops - a sequence of unary operators
      Returns:
      the value resulting from applying the first operator to the start value, the second operator to that value, etc.

    • applyAll

      public static <A> A applyAll(A start, Iterable<? extends UnaryOperator<A>> ops)
      Applies a sequence of unary operators in sequence to a start value.
      Type Parameters:
      A - the type of values
      Parameters:
      start - the start value
      ops - a sequence of unary operators
      Returns:
      the value resulting from applying the first operator to the start value, the second operator to that value, etc.

    • merge

      public static <A> BinaryOperator<A> merge()
      Returns a binary function that returns one of its arguments if they are equal.
      Type Parameters:
      A - the type of values
      Returns:
      a binary function that returns one of its arguments if they are equal, but throws IllegalArgumentException otherwise