Java tutorial
/* * Copyright (C) 2007 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.base; import static com.google.common.base.Preconditions.checkArgument; import static com.google.common.base.Preconditions.checkNotNull; import com.google.common.annotations.Beta; import com.google.common.annotations.GwtCompatible; import java.io.Serializable; import java.util.Map; import javax.annotation.CheckReturnValue; import javax.annotation.Nullable; /** * Static utility methods pertaining to {@code Function} instances. * * <p>All methods return serializable functions as long as they're given serializable parameters. * * <p>See the Guava User Guide article on <a href= * "https://github.com/google/guava/wiki/FunctionalExplained">the use of {@code * Function}</a>. * * @author Mike Bostock * @author Jared Levy * @since 2.0 */ @GwtCompatible @CheckReturnValue public final class Functions { private Functions() { } /** * Returns a function that calls {@code toString()} on its argument. The function does not accept * nulls; it will throw a {@link NullPointerException} when applied to {@code null}. * * <p><b>Warning:</b> The returned function may not be <i>consistent with equals</i> (as * documented at {@link Function#apply}). For example, this function yields different results for * the two equal instances {@code ImmutableSet.of(1, 2)} and {@code ImmutableSet.of(2, 1)}. */ public static Function<Object, String> toStringFunction() { return ToStringFunction.INSTANCE; } // enum singleton pattern private enum ToStringFunction implements Function<Object, String> { INSTANCE; @Override public String apply(Object o) { checkNotNull(o); // eager for GWT. return o.toString(); } @Override public String toString() { return "Functions.toStringFunction()"; } } /** * Returns the identity function. */ // implementation is "fully variant"; E has become a "pass-through" type @SuppressWarnings("unchecked") public static <E> Function<E, E> identity() { return (Function<E, E>) IdentityFunction.INSTANCE; } // enum singleton pattern private enum IdentityFunction implements Function<Object, Object> { INSTANCE; @Override @Nullable public Object apply(@Nullable Object o) { return o; } @Override public String toString() { return "Functions.identity()"; } } /** * Returns a function which performs a map lookup. The returned function throws an {@link * IllegalArgumentException} if given a key that does not exist in the map. See also {@link * #forMap(Map, Object)}, which returns a default value in this case. * * <p>Note: if {@code map} is a {@link com.google.common.collect.BiMap BiMap} (or can be one), you * can use {@link com.google.common.collect.Maps#asConverter Maps.asConverter} instead to get a * function that also supports reverse conversion. */ public static <K, V> Function<K, V> forMap(Map<K, V> map) { return new FunctionForMapNoDefault<K, V>(map); } private static class FunctionForMapNoDefault<K, V> implements Function<K, V>, Serializable { final Map<K, V> map; FunctionForMapNoDefault(Map<K, V> map) { this.map = checkNotNull(map); } @Override public V apply(@Nullable K key) { V result = map.get(key); checkArgument(result != null || map.containsKey(key), "Key '%s' not present in map", key); return result; } @Override public boolean equals(@Nullable Object o) { if (o instanceof FunctionForMapNoDefault) { FunctionForMapNoDefault<?, ?> that = (FunctionForMapNoDefault<?, ?>) o; return map.equals(that.map); } return false; } @Override public int hashCode() { return map.hashCode(); } @Override public String toString() { return "Functions.forMap(" + map + ")"; } private static final long serialVersionUID = 0; } /** * Returns a function which performs a map lookup with a default value. The function created by * this method returns {@code defaultValue} for all inputs that do not belong to the map's key * set. See also {@link #forMap(Map)}, which throws an exception in this case. * * @param map source map that determines the function behavior * @param defaultValue the value to return for inputs that aren't map keys * @return function that returns {@code map.get(a)} when {@code a} is a key, or {@code * defaultValue} otherwise */ public static <K, V> Function<K, V> forMap(Map<K, ? extends V> map, @Nullable V defaultValue) { return new ForMapWithDefault<K, V>(map, defaultValue); } private static class ForMapWithDefault<K, V> implements Function<K, V>, Serializable { final Map<K, ? extends V> map; final V defaultValue; ForMapWithDefault(Map<K, ? extends V> map, @Nullable V defaultValue) { this.map = checkNotNull(map); this.defaultValue = defaultValue; } @Override public V apply(@Nullable K key) { V result = map.get(key); return (result != null || map.containsKey(key)) ? result : defaultValue; } @Override public boolean equals(@Nullable Object o) { if (o instanceof ForMapWithDefault) { ForMapWithDefault<?, ?> that = (ForMapWithDefault<?, ?>) o; return map.equals(that.map) && Objects.equal(defaultValue, that.defaultValue); } return false; } @Override public int hashCode() { return Objects.hashCode(map, defaultValue); } @Override public String toString() { // TODO(cpovirk): maybe remove "defaultValue=" to make this look like the method call does return "Functions.forMap(" + map + ", defaultValue=" + defaultValue + ")"; } private static final long serialVersionUID = 0; } /** * Returns the composition of two functions. For {@code f: A->B} and {@code g: B->C}, composition * is defined as the function h such that {@code h(a) == g(f(a))} for each {@code a}. * * @param g the second function to apply * @param f the first function to apply * @return the composition of {@code f} and {@code g} * @see <a href="//en.wikipedia.org/wiki/Function_composition">function composition</a> */ public static <A, B, C> Function<A, C> compose(Function<B, C> g, Function<A, ? extends B> f) { return new FunctionComposition<A, B, C>(g, f); } private static class FunctionComposition<A, B, C> implements Function<A, C>, Serializable { private final Function<B, C> g; private final Function<A, ? extends B> f; public FunctionComposition(Function<B, C> g, Function<A, ? extends B> f) { this.g = checkNotNull(g); this.f = checkNotNull(f); } @Override public C apply(@Nullable A a) { return g.apply(f.apply(a)); } @Override public boolean equals(@Nullable Object obj) { if (obj instanceof FunctionComposition) { FunctionComposition<?, ?, ?> that = (FunctionComposition<?, ?, ?>) obj; return f.equals(that.f) && g.equals(that.g); } return false; } @Override public int hashCode() { return f.hashCode() ^ g.hashCode(); } @Override public String toString() { // TODO(cpovirk): maybe make this look like the method call does ("Functions.compose(...)") return g + "(" + f + ")"; } private static final long serialVersionUID = 0; } /** * Creates a function that returns the same boolean output as the given predicate for all inputs. * * <p>The returned function is <i>consistent with equals</i> (as documented at {@link * Function#apply}) if and only if {@code predicate} is itself consistent with equals. */ public static <T> Function<T, Boolean> forPredicate(Predicate<T> predicate) { return new PredicateFunction<T>(predicate); } /** @see Functions#forPredicate */ private static class PredicateFunction<T> implements Function<T, Boolean>, Serializable { private final Predicate<T> predicate; private PredicateFunction(Predicate<T> predicate) { this.predicate = checkNotNull(predicate); } @Override public Boolean apply(@Nullable T t) { return predicate.apply(t); } @Override public boolean equals(@Nullable Object obj) { if (obj instanceof PredicateFunction) { PredicateFunction<?> that = (PredicateFunction<?>) obj; return predicate.equals(that.predicate); } return false; } @Override public int hashCode() { return predicate.hashCode(); } @Override public String toString() { return "Functions.forPredicate(" + predicate + ")"; } private static final long serialVersionUID = 0; } /** * Creates a function that returns {@code value} for any input. * * @param value the constant value for the function to return * @return a function that always returns {@code value} */ public static <E> Function<Object, E> constant(@Nullable E value) { return new ConstantFunction<E>(value); } private static class ConstantFunction<E> implements Function<Object, E>, Serializable { private final E value; public ConstantFunction(@Nullable E value) { this.value = value; } @Override public E apply(@Nullable Object from) { return value; } @Override public boolean equals(@Nullable Object obj) { if (obj instanceof ConstantFunction) { ConstantFunction<?> that = (ConstantFunction<?>) obj; return Objects.equal(value, that.value); } return false; } @Override public int hashCode() { return (value == null) ? 0 : value.hashCode(); } @Override public String toString() { return "Functions.constant(" + value + ")"; } private static final long serialVersionUID = 0; } /** * Returns a function that always returns the result of invoking {@link Supplier#get} on {@code * supplier}, regardless of its input. * * @since 10.0 */ @Beta public static <T> Function<Object, T> forSupplier(Supplier<T> supplier) { return new SupplierFunction<T>(supplier); } /** @see Functions#forSupplier*/ private static class SupplierFunction<T> implements Function<Object, T>, Serializable { private final Supplier<T> supplier; private SupplierFunction(Supplier<T> supplier) { this.supplier = checkNotNull(supplier); } @Override public T apply(@Nullable Object input) { return supplier.get(); } @Override public boolean equals(@Nullable Object obj) { if (obj instanceof SupplierFunction) { SupplierFunction<?> that = (SupplierFunction<?>) obj; return this.supplier.equals(that.supplier); } return false; } @Override public int hashCode() { return supplier.hashCode(); } @Override public String toString() { return "Functions.forSupplier(" + supplier + ")"; } private static final long serialVersionUID = 0; } }