001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.common.base;
018
019import static com.google.common.base.Preconditions.checkArgument;
020import static com.google.common.base.Preconditions.checkNotNull;
021
022import com.google.common.annotations.Beta;
023import com.google.common.annotations.GwtCompatible;
024
025import java.io.Serializable;
026import java.util.Map;
027
028import javax.annotation.Nullable;
029
030/**
031 * Static utility methods pertaining to {@code Function} instances.
032 *
033 * <p>All methods return serializable functions as long as they're given serializable parameters.
034 * 
035 * <p>See the Guava User Guide article on <a href=
036 * "http://code.google.com/p/guava-libraries/wiki/FunctionalExplained">the use of {@code
037 * Function}</a>.
038 *
039 * @author Mike Bostock
040 * @author Jared Levy
041 * @since 2.0 (imported from Google Collections Library)
042 */
043@GwtCompatible
044public final class Functions {
045  private Functions() {}
046
047  /**
048   * Returns a function that calls {@code toString()} on its argument. The function does not accept
049   * nulls; it will throw a {@link NullPointerException} when applied to {@code null}.
050   *
051   * <p><b>Warning:</b> The returned function may not be <i>consistent with equals</i> (as
052   * documented at {@link Function#apply}). For example, this function yields different results for
053   * the two equal instances {@code ImmutableSet.of(1, 2)} and {@code ImmutableSet.of(2, 1)}.
054   */
055  public static Function<Object, String> toStringFunction() {
056    return ToStringFunction.INSTANCE;
057  }
058
059  // enum singleton pattern
060  private enum ToStringFunction implements Function<Object, String> {
061    INSTANCE;
062
063    @Override
064    public String apply(Object o) {
065      checkNotNull(o);  // eager for GWT.
066      return o.toString();
067    }
068
069    @Override public String toString() {
070      return "toString";
071    }
072  }
073
074  /**
075   * Returns the identity function.
076   */
077  @SuppressWarnings("unchecked")
078  public static <E> Function<E, E> identity() {
079    return (Function<E, E>) IdentityFunction.INSTANCE;
080  }
081
082  // enum singleton pattern
083  private enum IdentityFunction implements Function<Object, Object> {
084    INSTANCE;
085
086    @Override
087    public Object apply(Object o) {
088      return o;
089    }
090
091    @Override public String toString() {
092      return "identity";
093    }
094  }
095
096  /**
097   * Returns a function which performs a map lookup. The returned function throws an {@link
098   * IllegalArgumentException} if given a key that does not exist in the map.
099   */
100  public static <K, V> Function<K, V> forMap(Map<K, V> map) {
101    return new FunctionForMapNoDefault<K, V>(map);
102  }
103
104  private static class FunctionForMapNoDefault<K, V> implements Function<K, V>, Serializable {
105    final Map<K, V> map;
106
107    FunctionForMapNoDefault(Map<K, V> map) {
108      this.map = checkNotNull(map);
109    }
110
111    @Override
112    public V apply(K key) {
113      V result = map.get(key);
114      checkArgument(result != null || map.containsKey(key), "Key '%s' not present in map", key);
115      return result;
116    }
117
118    @Override public boolean equals(@Nullable Object o) {
119      if (o instanceof FunctionForMapNoDefault) {
120        FunctionForMapNoDefault<?, ?> that = (FunctionForMapNoDefault<?, ?>) o;
121        return map.equals(that.map);
122      }
123      return false;
124    }
125
126    @Override public int hashCode() {
127      return map.hashCode();
128    }
129
130    @Override public String toString() {
131      return "forMap(" + map + ")";
132    }
133
134    private static final long serialVersionUID = 0;
135  }
136
137  /**
138   * Returns a function which performs a map lookup with a default value. The function created by
139   * this method returns {@code defaultValue} for all inputs that do not belong to the map's key
140   * set.
141   *
142   * @param map source map that determines the function behavior
143   * @param defaultValue the value to return for inputs that aren't map keys
144   * @return function that returns {@code map.get(a)} when {@code a} is a key, or {@code
145   *         defaultValue} otherwise
146   */
147  public static <K, V> Function<K, V> forMap(Map<K, ? extends V> map, @Nullable V defaultValue) {
148    return new ForMapWithDefault<K, V>(map, defaultValue);
149  }
150
151  private static class ForMapWithDefault<K, V> implements Function<K, V>, Serializable {
152    final Map<K, ? extends V> map;
153    final V defaultValue;
154
155    ForMapWithDefault(Map<K, ? extends V> map, @Nullable V defaultValue) {
156      this.map = checkNotNull(map);
157      this.defaultValue = defaultValue;
158    }
159
160    @Override
161    public V apply(K key) {
162      V result = map.get(key);
163      return (result != null || map.containsKey(key)) ? result : defaultValue;
164    }
165
166    @Override public boolean equals(@Nullable Object o) {
167      if (o instanceof ForMapWithDefault) {
168        ForMapWithDefault<?, ?> that = (ForMapWithDefault<?, ?>) o;
169        return map.equals(that.map) && Objects.equal(defaultValue, that.defaultValue);
170      }
171      return false;
172    }
173
174    @Override public int hashCode() {
175      return Objects.hashCode(map, defaultValue);
176    }
177
178    @Override public String toString() {
179      return "forMap(" + map + ", defaultValue=" + defaultValue + ")";
180    }
181
182    private static final long serialVersionUID = 0;
183  }
184
185  /**
186   * Returns the composition of two functions. For {@code f: A->B} and {@code g: B->C}, composition
187   * is defined as the function h such that {@code h(a) == g(f(a))} for each {@code a}.
188   *
189   * @param g the second function to apply
190   * @param f the first function to apply
191   * @return the composition of {@code f} and {@code g}
192   * @see <a href="//en.wikipedia.org/wiki/Function_composition">function composition</a>
193   */
194  public static <A, B, C> Function<A, C> compose(Function<B, C> g, Function<A, ? extends B> f) {
195    return new FunctionComposition<A, B, C>(g, f);
196  }
197
198  private static class FunctionComposition<A, B, C> implements Function<A, C>, Serializable {
199    private final Function<B, C> g;
200    private final Function<A, ? extends B> f;
201
202    public FunctionComposition(Function<B, C> g, Function<A, ? extends B> f) {
203      this.g = checkNotNull(g);
204      this.f = checkNotNull(f);
205    }
206
207    @Override
208    public C apply(A a) {
209      return g.apply(f.apply(a));
210    }
211
212    @Override public boolean equals(@Nullable Object obj) {
213      if (obj instanceof FunctionComposition) {
214        FunctionComposition<?, ?, ?> that = (FunctionComposition<?, ?, ?>) obj;
215        return f.equals(that.f) && g.equals(that.g);
216      }
217      return false;
218    }
219
220    @Override public int hashCode() {
221      return f.hashCode() ^ g.hashCode();
222    }
223
224    @Override public String toString() {
225      return g.toString() + "(" + f.toString() + ")";
226    }
227
228    private static final long serialVersionUID = 0;
229  }
230
231  /**
232   * Creates a function that returns the same boolean output as the given predicate for all inputs.
233   *
234   * <p>The returned function is <i>consistent with equals</i> (as documented at {@link
235   * Function#apply}) if and only if {@code predicate} is itself consistent with equals.
236   */
237  public static <T> Function<T, Boolean> forPredicate(Predicate<T> predicate) {
238    return new PredicateFunction<T>(predicate);
239  }
240
241  /** @see Functions#forPredicate */
242  private static class PredicateFunction<T> implements Function<T, Boolean>, Serializable {
243    private final Predicate<T> predicate;
244
245    private PredicateFunction(Predicate<T> predicate) {
246      this.predicate = checkNotNull(predicate);
247    }
248
249    @Override
250    public Boolean apply(T t) {
251      return predicate.apply(t);
252    }
253
254    @Override public boolean equals(@Nullable Object obj) {
255      if (obj instanceof PredicateFunction) {
256        PredicateFunction<?> that = (PredicateFunction<?>) obj;
257        return predicate.equals(that.predicate);
258      }
259      return false;
260    }
261
262    @Override public int hashCode() {
263      return predicate.hashCode();
264    }
265
266    @Override public String toString() {
267      return "forPredicate(" + predicate + ")";
268    }
269
270    private static final long serialVersionUID = 0;
271  }
272
273  /**
274   * Creates a function that returns {@code value} for any input.
275   *
276   * @param value the constant value for the function to return
277   * @return a function that always returns {@code value}
278   */
279  public static <E> Function<Object, E> constant(@Nullable E value) {
280    return new ConstantFunction<E>(value);
281  }
282
283  private static class ConstantFunction<E> implements Function<Object, E>, Serializable {
284    private final E value;
285
286    public ConstantFunction(@Nullable E value) {
287      this.value = value;
288    }
289
290    @Override
291    public E apply(@Nullable Object from) {
292      return value;
293    }
294
295    @Override public boolean equals(@Nullable Object obj) {
296      if (obj instanceof ConstantFunction) {
297        ConstantFunction<?> that = (ConstantFunction<?>) obj;
298        return Objects.equal(value, that.value);
299      }
300      return false;
301    }
302
303    @Override public int hashCode() {
304      return (value == null) ? 0 : value.hashCode();
305    }
306
307    @Override public String toString() {
308      return "constant(" + value + ")";
309    }
310
311    private static final long serialVersionUID = 0;
312  }
313
314  /**
315   * Returns a function that always returns the result of invoking {@link Supplier#get} on {@code
316   * supplier}, regardless of its input.
317   * 
318   * @since 10.0
319   */
320  @Beta
321  public static <T> Function<Object, T> forSupplier(Supplier<T> supplier) {
322    return new SupplierFunction<T>(supplier);
323  }
324
325  /** @see Functions#forSupplier*/
326  private static class SupplierFunction<T> implements Function<Object, T>, Serializable {
327    
328    private final Supplier<T> supplier;
329
330    private SupplierFunction(Supplier<T> supplier) {
331      this.supplier = checkNotNull(supplier);
332    }
333
334    @Override public T apply(@Nullable Object input) {
335      return supplier.get();
336    }
337    
338    @Override public boolean equals(@Nullable Object obj) {
339      if (obj instanceof SupplierFunction) {
340        SupplierFunction<?> that = (SupplierFunction<?>) obj;
341        return this.supplier.equals(that.supplier);
342      }
343      return false;
344    }
345    
346    @Override public int hashCode() {
347      return supplier.hashCode();
348    }
349    
350    @Override public String toString() {
351      return "forSupplier(" + supplier + ")";
352    }
353    
354    private static final long serialVersionUID = 0;
355  }
356}