Package com.google.common.base

Class Functions

  • @GwtCompatible
public final class Functions
extends java.lang.Object
    Static utility methods pertaining to com.google.common.base.Function instances; see that class for information about migrating to java.util.function.

    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
    Author:
    Mike Bostock, Jared Levy

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <A extends @Nullable java.lang.Object,​B extends @Nullable java.lang.Object,​C extends @Nullable java.lang.Object>
      Function<A,​C>      		 compose​(Function<B,​C> g, Function<A,​? extends B> f)
      Returns the composition of two functions.
      static <E extends @Nullable java.lang.Object>
      Function<@Nullable java.lang.Object,​E>      		 constant​(E value)
      Returns a function that ignores its input and always returns value.
      static <K extends @Nullable java.lang.Object,​V extends @Nullable java.lang.Object>
      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 extends @Nullable java.lang.Object,​V extends @Nullable java.lang.Object>
      Function<K,​V>      		 forMap​(java.util.Map<K,​V> map)
      Returns a function which performs a map lookup.
      static <T extends @Nullable java.lang.Object>
      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 <F extends @Nullable java.lang.Object,​T extends @Nullable java.lang.Object>
      Function<F,​T>      		 forSupplier​(Supplier<T> supplier)
      Returns a function that ignores its input and returns the result of supplier.get().
      static <E extends @Nullable java.lang.Object>
      Function<E,​E>      		 identity()
      Returns the identity function.
      static Function<java.lang.Object,​java.lang.String> toStringFunction()
      A function equivalent to the method reference Object::toString.

      • 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()
        A function equivalent to the method reference Object::toString. The function simply invokes toString on its argument and returns the result. It throws a NullPointerException on null input.

        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).

        Warning: as with all function types in this package, avoid depending on the specific equals, hashCode or toString behavior of the returned function. A future migration to java.util.function will not preserve this behavior.

        As discussed above, prefer to use the method reference Object::toString instead, though note that it is not serializable unless you explicitly make it Serializable, typically by writing (Function<Object, String> & Serializable) Object::toString.

        For more important information about the transition from Guava's Function class to the JDK Function class, see Function.

      • identity

        public static <E extends @Nullable java.lang.Object> Function<E,​E> identity()
        Returns the identity function.

        Discouraged: Prefer using a lambda like v -> v, which is shorter and often more readable.

      • forMap

        public static <K extends @Nullable java.lang.Object,​V extends @Nullable java.lang.Object> 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.

        If you are okay with null being returned for an unrecognized key (instead of an exception being thrown), you can use the method reference map::get instead. Note that it is not serializable unless you explicitly make it Serializable, typically by writing (Function<K, V> & Serializable) map::get.

      • forMap

        public static <K extends @Nullable java.lang.Object,​V extends @Nullable java.lang.Object> 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. 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.

        Prefer to write the lambda expression k -> map.getOrDefault(k, defaultValue) instead. Note that it is not serializable unless you explicitly make it Serializable, typically by writing (Function<K, V> & Serializable) k -> map.getOrDefault(k, defaultValue).

        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 extends @Nullable java.lang.Object,​B extends @Nullable java.lang.Object,​C extends @Nullable java.lang.Object> 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.

        JRE users and Android users who opt in to library desugaring: use g.compose(f) or (probably clearer) f.andThen(g) instead. Note that it is not serializable.

        Parameters:
        g - the second function to apply
        f - the first function to apply

      • forPredicate

        public static <T extends @Nullable java.lang.Object> 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.

        Prefer to use the method reference predicate::test instead. Note that it is not serializable unless you explicitly make it Serializable, typically by writing (Function<T, Boolean> & Serializable) predicate::test.

      • constant

        public static <E extends @Nullable java.lang.Object> Function<@Nullable java.lang.Object,​E> constant​(E value)
        Returns a function that ignores its input and always returns value.

        Prefer to use the lambda expression o -> value instead. Note that it is not serializable unless you explicitly make it Serializable, typically by writing (Function<Object, E> & Serializable) o -> value.

        Parameters:
        value - the constant value for the function to return
        Returns:
        a function that always returns value

      • forSupplier

        public static <F extends @Nullable java.lang.Object,​T extends @Nullable java.lang.Object> Function<F,​T> forSupplier​(Supplier<T> supplier)
        Returns a function that ignores its input and returns the result of supplier.get().

        Prefer to use the lambda expression o -> supplier.get() instead. Note that it is not serializable unless you explicitly make it Serializable, typically by writing (Function<F, T> & Serializable) o -> supplier.get().

        Since:
        10.0