Functions
Date: 2016-05-24

com.google.common.base

## Class Functions

- java.lang.Object
- - com.google.common.base.Functions

-     @GwtCompatible
      @CheckReturnValue
      public final class Functions
      extends java.lang.Object

  Static utility methods pertaining to `Function` instances.

  All methods return serializable functions as long as they're given serializable parameters.

  See the Guava User Guide article on the use of `Function`.

  Since:
    2.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <A,B,C> Function<A,C>` | `compose(Function<B,C> g, Function<A,? extends B> f)` Returns the composition of two functions.
    `static <E> Function<java.lang.Object,E>` | `constant(E value)` Creates a function that returns `value` for any input.
    `static <K,V> Function<K,V>` | `forMap(java.util.Map<K,? extends V> map, V defaultValue)` Returns a function which performs a map lookup with a default value.
    `static <K,V> Function<K,V>` | `forMap(java.util.Map<K,V> map)` Returns a function which performs a map lookup.
    `static <T> Function<T,java.lang.Boolean>` | `forPredicate(Predicate<T> predicate)` Creates a function that returns the same boolean output as the given predicate for all inputs.
    `static <T> Function<java.lang.Object,T>` | `forSupplier(Supplier<T> supplier)` Returns a function that always returns the result of invoking `Supplier.get()` on `supplier`, regardless of its input.
    `static <E> Function<E,E>` | `identity()` Returns the identity function.
    `static Function<java.lang.Object,java.lang.String>` | `toStringFunction()` Returns a function that calls `toString()` on its argument.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### toStringFunction

          public static Function<java.lang.Object,java.lang.String> toStringFunction()

      Returns a function that calls `toString()` on its argument. The function does not accept nulls; it will throw a `NullPointerException` when applied to `null`.

      Warning: The returned function may not be consistent with equals (as documented at `Function.apply(F)`). For example, this function yields different results for the two equal instances `ImmutableSet.of(1, 2)` and `ImmutableSet.of(2, 1)`.

    - #### identity

          public static <E> Function<E,E> identity()

      Returns the identity function.

    - #### forMap

          public static <K,V> Function<K,V> forMap(java.util.Map<K,V> map)

      Returns a function which performs a map lookup. The returned function throws an `IllegalArgumentException` if given a key that does not exist in the map. See also `forMap(Map, Object)`, which returns a default value in this case.

      Note: if `map` is a `BiMap` (or can be one), you can use `Maps.asConverter` instead to get a function that also supports reverse conversion.

    - #### forMap

          public static <K,V> Function<K,V> forMap(java.util.Map<K,? extends V> map,
                                   @Nullable
                                   V defaultValue)

      Returns a function which performs a map lookup with a default value. The function created by this method returns `defaultValue` for all inputs that do not belong to the map's key set. See also `forMap(Map)`, which throws an exception in this case.
      Parameters:
        `map` - source map that determines the function behavior
        `defaultValue` - the value to return for inputs that aren't map keys
      Returns:
        function that returns `map.get(a)` when `a` is a key, or `defaultValue` otherwise

    - #### compose

          public static <A,B,C> Function<A,C> compose(Function<B,C> g,
                                      Function<A,? extends B> f)

      Returns the composition of two functions. For `f: A->B` and `g: B->C`, composition is defined as the function h such that `h(a) == g(f(a))` for each `a`.
      Parameters:
        `g` - the second function to apply
        `f` - the first function to apply
      Returns:
        the composition of `f` and `g`
      See Also:
        function composition

    - #### forPredicate

          public static <T> Function<T,java.lang.Boolean> forPredicate(Predicate<T> predicate)

      Creates a function that returns the same boolean output as the given predicate for all inputs.

      The returned function is consistent with equals (as documented at `Function.apply(F)`) if and only if `predicate` is itself consistent with equals.

    - #### constant

          public static <E> Function<java.lang.Object,E> constant(@Nullable
                                                  E value)

      Creates a function that returns `value` for any input.
      Parameters:
        `value` - the constant value for the function to return
      Returns:
        a function that always returns `value`

    - #### forSupplier

          @Beta
          public static <T> Function<java.lang.Object,T> forSupplier(Supplier<T> supplier)

      Returns a function that always returns the result of invoking `Supplier.get()` on `supplier`, regardless of its input.
      Since:
        10.0