001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.base;
016
017import static com.google.common.base.NullnessCasts.uncheckedCastNullableTToT;
018import static com.google.common.base.Preconditions.checkArgument;
019import static com.google.common.base.Preconditions.checkNotNull;
020
021import com.google.common.annotations.GwtCompatible;
022import java.io.Serializable;
023import java.util.Map;
024import javax.annotation.CheckForNull;
025import org.checkerframework.checker.nullness.qual.Nullable;
026
027/**
028 * Static utility methods pertaining to {@code com.google.common.base.Function} instances; see that
029 * class for information about migrating to {@code java.util.function}.
030 *
031 * <p>All methods return serializable functions as long as they're given serializable parameters.
032 *
033 * <p>See the Guava User Guide article on <a
034 * href="https://github.com/google/guava/wiki/FunctionalExplained">the use of {@code Function}</a>.
035 *
036 * @author Mike Bostock
037 * @author Jared Levy
038 * @since 2.0
039 */
040@GwtCompatible
041@ElementTypesAreNonnullByDefault
042public final class Functions {
043  private Functions() {}
044
045  /**
046   * A function equivalent to the method reference {@code Object::toString}, for users not yet using
047   * Java 8. The function simply invokes {@code toString} on its argument and returns the result. It
048   * throws a {@link NullPointerException} on null input.
049   *
050   * <p><b>Warning:</b> The returned function may not be <i>consistent with equals</i> (as
051   * documented at {@link Function#apply}). For example, this function yields different results for
052   * the two equal instances {@code ImmutableSet.of(1, 2)} and {@code ImmutableSet.of(2, 1)}.
053   *
054   * <p><b>Warning:</b> as with all function types in this package, avoid depending on the specific
055   * {@code equals}, {@code hashCode} or {@code toString} behavior of the returned function. A
056   * future migration to {@code java.util.function} will not preserve this behavior.
057   *
058   * <p><b>For Java 8 users:</b> use the method reference {@code Object::toString} instead. In the
059   * future, when this class requires Java 8, this method will be deprecated. See {@link Function}
060   * for more important information about the Java 8 transition.
061   */
062  public static Function<Object, String> toStringFunction() {
063    return ToStringFunction.INSTANCE;
064  }
065
066  // enum singleton pattern
067  private enum ToStringFunction implements Function<Object, String> {
068    INSTANCE;
069
070    @Override
071    public String apply(Object o) {
072      checkNotNull(o); // eager for GWT.
073      return o.toString();
074    }
075
076    @Override
077    public String toString() {
078      return "Functions.toStringFunction()";
079    }
080  }
081
082  /** Returns the identity function. */
083  // implementation is "fully variant"; E has become a "pass-through" type
084  @SuppressWarnings("unchecked")
085  public static <E extends @Nullable Object> Function<E, E> identity() {
086    return (Function<E, E>) IdentityFunction.INSTANCE;
087  }
088
089  // enum singleton pattern
090  private enum IdentityFunction implements Function<@Nullable Object, @Nullable Object> {
091    INSTANCE;
092
093    @Override
094    @CheckForNull
095    public Object apply(@CheckForNull Object o) {
096      return o;
097    }
098
099    @Override
100    public String toString() {
101      return "Functions.identity()";
102    }
103  }
104
105  /**
106   * Returns a function which performs a map lookup. The returned function throws an {@link
107   * IllegalArgumentException} if given a key that does not exist in the map. See also {@link
108   * #forMap(Map, Object)}, which returns a default value in this case.
109   *
110   * <p>Note: if {@code map} is a {@link com.google.common.collect.BiMap BiMap} (or can be one), you
111   * can use {@link com.google.common.collect.Maps#asConverter Maps.asConverter} instead to get a
112   * function that also supports reverse conversion.
113   *
114   * <p><b>Java 8 users:</b> if you are okay with {@code null} being returned for an unrecognized
115   * key (instead of an exception being thrown), you can use the method reference {@code map::get}
116   * instead.
117   */
118  public static <K extends @Nullable Object, V extends @Nullable Object> Function<K, V> forMap(
119      Map<K, V> map) {
120    return new FunctionForMapNoDefault<>(map);
121  }
122
123  /**
124   * Returns a function which performs a map lookup with a default value. The function created by
125   * this method returns {@code defaultValue} for all inputs that do not belong to the map's key
126   * set. See also {@link #forMap(Map)}, which throws an exception in this case.
127   *
128   * <p><b>Java 8 users:</b> you can just write the lambda expression {@code k ->
129   * map.getOrDefault(k, defaultValue)} instead.
130   *
131   * @param map source map that determines the function behavior
132   * @param defaultValue the value to return for inputs that aren't map keys
133   * @return function that returns {@code map.get(a)} when {@code a} is a key, or {@code
134   *     defaultValue} otherwise
135   */
136  public static <K extends @Nullable Object, V extends @Nullable Object> Function<K, V> forMap(
137      Map<K, ? extends V> map, @ParametricNullness V defaultValue) {
138    return new ForMapWithDefault<>(map, defaultValue);
139  }
140
141  private static class FunctionForMapNoDefault<
142          K extends @Nullable Object, V extends @Nullable Object>
143      implements Function<K, V>, Serializable {
144    final Map<K, V> map;
145
146    FunctionForMapNoDefault(Map<K, V> map) {
147      this.map = checkNotNull(map);
148    }
149
150    @Override
151    @ParametricNullness
152    public V apply(@ParametricNullness K key) {
153      V result = map.get(key);
154      checkArgument(result != null || map.containsKey(key), "Key '%s' not present in map", key);
155      // The unchecked cast is safe because of the containsKey check.
156      return uncheckedCastNullableTToT(result);
157    }
158
159    @Override
160    public boolean equals(@CheckForNull Object o) {
161      if (o instanceof FunctionForMapNoDefault) {
162        FunctionForMapNoDefault<?, ?> that = (FunctionForMapNoDefault<?, ?>) o;
163        return map.equals(that.map);
164      }
165      return false;
166    }
167
168    @Override
169    public int hashCode() {
170      return map.hashCode();
171    }
172
173    @Override
174    public String toString() {
175      return "Functions.forMap(" + map + ")";
176    }
177
178    private static final long serialVersionUID = 0;
179  }
180
181  private static class ForMapWithDefault<K extends @Nullable Object, V extends @Nullable Object>
182      implements Function<K, V>, Serializable {
183    final Map<K, ? extends V> map;
184    @ParametricNullness final V defaultValue;
185
186    ForMapWithDefault(Map<K, ? extends V> map, @ParametricNullness V defaultValue) {
187      this.map = checkNotNull(map);
188      this.defaultValue = defaultValue;
189    }
190
191    @Override
192    @ParametricNullness
193    public V apply(@ParametricNullness K key) {
194      V result = map.get(key);
195      // The unchecked cast is safe because of the containsKey check.
196      return (result != null || map.containsKey(key))
197          ? uncheckedCastNullableTToT(result)
198          : defaultValue;
199    }
200
201    @Override
202    public boolean equals(@CheckForNull Object o) {
203      if (o instanceof ForMapWithDefault) {
204        ForMapWithDefault<?, ?> that = (ForMapWithDefault<?, ?>) o;
205        return map.equals(that.map) && Objects.equal(defaultValue, that.defaultValue);
206      }
207      return false;
208    }
209
210    @Override
211    public int hashCode() {
212      return Objects.hashCode(map, defaultValue);
213    }
214
215    @Override
216    public String toString() {
217      // TODO(cpovirk): maybe remove "defaultValue=" to make this look like the method call does
218      return "Functions.forMap(" + map + ", defaultValue=" + defaultValue + ")";
219    }
220
221    private static final long serialVersionUID = 0;
222  }
223
224  /**
225   * Returns the composition of two functions. For {@code f: A->B} and {@code g: B->C}, composition
226   * is defined as the function h such that {@code h(a) == g(f(a))} for each {@code a}.
227   *
228   * <p><b>Java 8 users:</b> use {@code g.compose(f)} or (probably clearer) {@code f.andThen(g)}
229   * instead.
230   *
231   * @param g the second function to apply
232   * @param f the first function to apply
233   * @return the composition of {@code f} and {@code g}
234   * @see <a href="//en.wikipedia.org/wiki/Function_composition">function composition</a>
235   */
236  public static <A extends @Nullable Object, B extends @Nullable Object, C extends @Nullable Object>
237      Function<A, C> compose(Function<B, C> g, Function<A, ? extends B> f) {
238    return new FunctionComposition<>(g, f);
239  }
240
241  private static class FunctionComposition<
242          A extends @Nullable Object, B extends @Nullable Object, C extends @Nullable Object>
243      implements Function<A, C>, Serializable {
244    private final Function<B, C> g;
245    private final Function<A, ? extends B> f;
246
247    public FunctionComposition(Function<B, C> g, Function<A, ? extends B> f) {
248      this.g = checkNotNull(g);
249      this.f = checkNotNull(f);
250    }
251
252    @Override
253    @ParametricNullness
254    public C apply(@ParametricNullness A a) {
255      return g.apply(f.apply(a));
256    }
257
258    @Override
259    public boolean equals(@CheckForNull Object obj) {
260      if (obj instanceof FunctionComposition) {
261        FunctionComposition<?, ?, ?> that = (FunctionComposition<?, ?, ?>) obj;
262        return f.equals(that.f) && g.equals(that.g);
263      }
264      return false;
265    }
266
267    @Override
268    public int hashCode() {
269      return f.hashCode() ^ g.hashCode();
270    }
271
272    @Override
273    public String toString() {
274      // TODO(cpovirk): maybe make this look like the method call does ("Functions.compose(...)")
275      return g + "(" + f + ")";
276    }
277
278    private static final long serialVersionUID = 0;
279  }
280
281  /**
282   * Creates a function that returns the same boolean output as the given predicate for all inputs.
283   *
284   * <p>The returned function is <i>consistent with equals</i> (as documented at {@link
285   * Function#apply}) if and only if {@code predicate} is itself consistent with equals.
286   *
287   * <p><b>Java 8 users:</b> use the method reference {@code predicate::test} instead.
288   */
289  public static <T extends @Nullable Object> Function<T, Boolean> forPredicate(
290      Predicate<T> predicate) {
291    return new PredicateFunction<>(predicate);
292  }
293
294  /** @see Functions#forPredicate */
295  private static class PredicateFunction<T extends @Nullable Object>
296      implements Function<T, Boolean>, Serializable {
297    private final Predicate<T> predicate;
298
299    private PredicateFunction(Predicate<T> predicate) {
300      this.predicate = checkNotNull(predicate);
301    }
302
303    @Override
304    public Boolean apply(@ParametricNullness T t) {
305      return predicate.apply(t);
306    }
307
308    @Override
309    public boolean equals(@CheckForNull Object obj) {
310      if (obj instanceof PredicateFunction) {
311        PredicateFunction<?> that = (PredicateFunction<?>) obj;
312        return predicate.equals(that.predicate);
313      }
314      return false;
315    }
316
317    @Override
318    public int hashCode() {
319      return predicate.hashCode();
320    }
321
322    @Override
323    public String toString() {
324      return "Functions.forPredicate(" + predicate + ")";
325    }
326
327    private static final long serialVersionUID = 0;
328  }
329
330  /**
331   * Returns a function that ignores its input and always returns {@code value}.
332   *
333   * <p><b>Java 8 users:</b> use the lambda expression {@code o -> value} instead.
334   *
335   * @param value the constant value for the function to return
336   * @return a function that always returns {@code value}
337   */
338  public static <E extends @Nullable Object> Function<@Nullable Object, E> constant(
339      @ParametricNullness E value) {
340    return new ConstantFunction<>(value);
341  }
342
343  private static class ConstantFunction<E extends @Nullable Object>
344      implements Function<@Nullable Object, E>, Serializable {
345    @ParametricNullness private final E value;
346
347    public ConstantFunction(@ParametricNullness E value) {
348      this.value = value;
349    }
350
351    @Override
352    @ParametricNullness
353    public E apply(@CheckForNull Object from) {
354      return value;
355    }
356
357    @Override
358    public boolean equals(@CheckForNull Object obj) {
359      if (obj instanceof ConstantFunction) {
360        ConstantFunction<?> that = (ConstantFunction<?>) obj;
361        return Objects.equal(value, that.value);
362      }
363      return false;
364    }
365
366    @Override
367    public int hashCode() {
368      return (value == null) ? 0 : value.hashCode();
369    }
370
371    @Override
372    public String toString() {
373      return "Functions.constant(" + value + ")";
374    }
375
376    private static final long serialVersionUID = 0;
377  }
378
379  /**
380   * Returns a function that ignores its input and returns the result of {@code supplier.get()}.
381   *
382   * <p><b>Java 8 users:</b> use the lambda expression {@code o -> supplier.get()} instead.
383   *
384   * @since 10.0
385   */
386  public static <F extends @Nullable Object, T extends @Nullable Object> Function<F, T> forSupplier(
387      Supplier<T> supplier) {
388    return new SupplierFunction<>(supplier);
389  }
390
391  /** @see Functions#forSupplier */
392  private static class SupplierFunction<F extends @Nullable Object, T extends @Nullable Object>
393      implements Function<F, T>, Serializable {
394
395    private final Supplier<T> supplier;
396
397    private SupplierFunction(Supplier<T> supplier) {
398      this.supplier = checkNotNull(supplier);
399    }
400
401    @Override
402    @ParametricNullness
403    public T apply(@ParametricNullness F input) {
404      return supplier.get();
405    }
406
407    @Override
408    public boolean equals(@CheckForNull Object obj) {
409      if (obj instanceof SupplierFunction) {
410        SupplierFunction<?, ?> that = (SupplierFunction<?, ?>) obj;
411        return this.supplier.equals(that.supplier);
412      }
413      return false;
414    }
415
416    @Override
417    public int hashCode() {
418      return supplier.hashCode();
419    }
420
421    @Override
422    public String toString() {
423      return "Functions.forSupplier(" + supplier + ")";
424    }
425
426    private static final long serialVersionUID = 0;
427  }
428}