com.google.common.base.Functions Maven / Gradle / Ivy
/*
* 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.Nullable;
/**
* Static utility methods pertaining to {@code 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 {@code
* Function}.
*
* @author Mike Bostock
* @author Jared Levy
* @since 2.0 (imported from Google Collections Library)
*/
@GwtCompatible
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}.
*
*
Warning: The returned function may not be consistent with equals (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 toStringFunction() {
return ToStringFunction.INSTANCE;
}
// enum singleton pattern
private enum ToStringFunction implements Function {
INSTANCE;
@Override
public String apply(Object o) {
checkNotNull(o); // eager for GWT.
return o.toString();
}
@Override public String toString() {
return "toString";
}
}
/**
* Returns the identity function.
*/
// implementation is "fully variant"; E has become a "pass-through" type
@SuppressWarnings("unchecked")
public static Function identity() {
return (Function) IdentityFunction.INSTANCE;
}
// enum singleton pattern
private enum IdentityFunction implements Function {
INSTANCE;
@Override
@Nullable
public Object apply(@Nullable Object o) {
return o;
}
@Override public String toString() {
return "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.
*
* 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 Function forMap(Map map) {
return new FunctionForMapNoDefault(map);
}
private static class FunctionForMapNoDefault implements Function, Serializable {
final Map map;
FunctionForMapNoDefault(Map 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 "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 Function forMap(Map map, @Nullable V defaultValue) {
return new ForMapWithDefault(map, defaultValue);
}
private static class ForMapWithDefault implements Function, Serializable {
final Map map;
final V defaultValue;
ForMapWithDefault(Map 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() {
return "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 function composition
*/
public static Function compose(Function g, Function f) {
return new FunctionComposition(g, f);
}
private static class FunctionComposition implements Function, Serializable {
private final Function g;
private final Function f;
public FunctionComposition(Function g, Function 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() {
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.
*
* The returned function is consistent with equals (as documented at {@link
* Function#apply}) if and only if {@code predicate} is itself consistent with equals.
*/
public static Function forPredicate(Predicate predicate) {
return new PredicateFunction(predicate);
}
/** @see Functions#forPredicate */
private static class PredicateFunction implements Function, Serializable {
private final Predicate predicate;
private PredicateFunction(Predicate 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 "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 Function constant(@Nullable E value) {
return new ConstantFunction(value);
}
private static class ConstantFunction implements Function, 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 "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 Function forSupplier(Supplier supplier) {
return new SupplierFunction(supplier);
}
/** @see Functions#forSupplier*/
private static class SupplierFunction implements Function, Serializable {
private final Supplier supplier;
private SupplierFunction(Supplier 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 "forSupplier(" + supplier + ")";
}
private static final long serialVersionUID = 0;
}
}