com.google.common.base

Class Functions

java.lang.Object

com.google.common.base.Functions

@GwtCompatible
public final class Functions
extends 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

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<Object,E>	constant(E value) Returns a function that ignores its input and always returns value.
static <K,V> Function<K,V>	forMap(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(Map<K,V> map) Returns a function which performs a map lookup.
static <T> Function<T,Boolean>	forPredicate(Predicate<T> predicate) Creates a function that returns the same boolean output as the given predicate for all inputs.
static <T> Function<Object,T>	forSupplier(Supplier<T> supplier) Returns a function that ignores its input and returns the result of supplier.get().
static <E> Function<E,E>	identity() Returns the identity function.
static Function<Object,String>	toStringFunction() A function equivalent to the method reference Object::toString, for users not yet using Java 8.

Methods inherited from class java.lang.Object

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

Method Detail

toStringFunction

public static Function<Object,String> toStringFunction()

A function equivalent to the method reference Object::toString, for users not yet using Java 8. 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.

For Java 8 users: use the method reference Object::toString instead. In the future, when this class requires Java 8, this method will be deprecated. See Function for more important information about the Java 8 transition.

identity

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

Returns the identity function.

forMap

public static <K,V> Function<K,V> forMap(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.

Java 8 users: 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.

forMap

public static <K,V> Function<K,V> forMap(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.

Java 8 users: you can just write the lambda expression k -> map.getOrDefault(k, defaultValue) instead.

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.

Java 8 users: use g.compose(f) or (probably clearer) f.andThen(g) instead.

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

Java 8 users: use the method reference predicate::test instead.

constant

public static <E> Function<Object,E> constant(E value)

Returns a function that ignores its input and always returns value.

Java 8 users: use the lambda expression o -> value instead.

Parameters:

value - the constant value for the function to return

Returns:

a function that always returns value

forSupplier

public static <T> Function<Object,T> forSupplier(Supplier<T> supplier)

Returns a function that ignores its input and returns the result of supplier.get().

Java 8 users: use the lambda expression o -> supplier.get() instead.

Since:

10.0