1 /*
2 * Copyright (C) 2007 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.base;
16
17 import static com.google.common.base.Preconditions.checkArgument;
18 import static com.google.common.base.Preconditions.checkNotNull;
19
20 import com.google.common.annotations.GwtCompatible;
21 import java.io.Serializable;
22 import java.util.Map;
23 import org.checkerframework.checker.nullness.qual.Nullable;
24
25 /**
26 * Static utility methods pertaining to {@code com.google.common.base.Function} instances; see that
27 * class for information about migrating to {@code java.util.function}.
28 *
29 * <p>All methods return serializable functions as long as they're given serializable parameters.
30 *
31 * <p>See the Guava User Guide article on <a
32 * href="https://github.com/google/guava/wiki/FunctionalExplained">the use of {@code Function}</a>.
33 *
34 * @author Mike Bostock
35 * @author Jared Levy
36 * @since 2.0
37 */
38 @GwtCompatible
39 public final class Functions {
40 private Functions() {}
41
42 /**
43 * A function equivalent to the method reference {@code Object::toString}, for users not yet using
44 * Java 8. The function simply invokes {@code toString} on its argument and returns the result. It
45 * throws a {@link NullPointerException} on null input.
46 *
47 * <p><b>Warning:</b> The returned function may not be <i>consistent with equals</i> (as
48 * documented at {@link Function#apply}). For example, this function yields different results for
49 * the two equal instances {@code ImmutableSet.of(1, 2)} and {@code ImmutableSet.of(2, 1)}.
50 *
51 * <p><b>Warning:</b> as with all function types in this package, avoid depending on the specific
52 * {@code equals}, {@code hashCode} or {@code toString} behavior of the returned function. A
53 * future migration to {@code java.util.function} will not preserve this behavior.
54 *
55 * <p><b>For Java 8 users:</b> use the method reference {@code Object::toString} instead. In the
56 * future, when this class requires Java 8, this method will be deprecated. See {@link Function}
57 * for more important information about the Java 8 transition.
58 */
59 public static Function<Object, String> toStringFunction() {
60 return ToStringFunction.INSTANCE;
61 }
62
63 // enum singleton pattern
64 private enum ToStringFunction implements Function<Object, String> {
65 INSTANCE;
66
67 @Override
68 public String apply(Object o) {
69 checkNotNull(o); // eager for GWT.
70 return o.toString();
71 }
72
73 @Override
74 public String toString() {
75 return "Functions.toStringFunction()";
76 }
77 }
78
79 /** Returns the identity function. */
80 // implementation is "fully variant"; E has become a "pass-through" type
81 @SuppressWarnings("unchecked")
82 public static <E> Function<E, E> identity() {
83 return (Function<E, E>) IdentityFunction.INSTANCE;
84 }
85
86 // enum singleton pattern
87 private enum IdentityFunction implements Function<Object, Object> {
88 INSTANCE;
89
90 @Override
91 public @Nullable Object apply(@Nullable Object o) {
92 return o;
93 }
94
95 @Override
96 public String toString() {
97 return "Functions.identity()";
98 }
99 }
100
101 /**
102 * Returns a function which performs a map lookup. The returned function throws an {@link
103 * IllegalArgumentException} if given a key that does not exist in the map. See also {@link
104 * #forMap(Map, Object)}, which returns a default value in this case.
105 *
106 * <p>Note: if {@code map} is a {@link com.google.common.collect.BiMap BiMap} (or can be one), you
107 * can use {@link com.google.common.collect.Maps#asConverter Maps.asConverter} instead to get a
108 * function that also supports reverse conversion.
109 *
110 * <p><b>Java 8 users:</b> if you are okay with {@code null} being returned for an unrecognized
111 * key (instead of an exception being thrown), you can use the method reference {@code map::get}
112 * instead.
113 */
114 public static <K, V> Function<K, V> forMap(Map<K, V> map) {
115 return new FunctionForMapNoDefault<>(map);
116 }
117
118 /**
119 * Returns a function which performs a map lookup with a default value. The function created by
120 * this method returns {@code defaultValue} for all inputs that do not belong to the map's key
121 * set. See also {@link #forMap(Map)}, which throws an exception in this case.
122 *
123 * <p><b>Java 8 users:</b> you can just write the lambda expression {@code k ->
124 * map.getOrDefault(k, defaultValue)} instead.
125 *
126 * @param map source map that determines the function behavior
127 * @param defaultValue the value to return for inputs that aren't map keys
128 * @return function that returns {@code map.get(a)} when {@code a} is a key, or {@code
129 * defaultValue} otherwise
130 */
131 public static <K, V> Function<K, V> forMap(Map<K, ? extends V> map, @Nullable V defaultValue) {
132 return new ForMapWithDefault<>(map, defaultValue);
133 }
134
135 private static class FunctionForMapNoDefault<K, V> implements Function<K, V>, Serializable {
136 final Map<K, V> map;
137
138 FunctionForMapNoDefault(Map<K, V> map) {
139 this.map = checkNotNull(map);
140 }
141
142 @Override
143 public V apply(@Nullable K key) {
144 V result = map.get(key);
145 checkArgument(result != null || map.containsKey(key), "Key '%s' not present in map", key);
146 return result;
147 }
148
149 @Override
150 public boolean equals(@Nullable Object o) {
151 if (o instanceof FunctionForMapNoDefault) {
152 FunctionForMapNoDefault<?, ?> that = (FunctionForMapNoDefault<?, ?>) o;
153 return map.equals(that.map);
154 }
155 return false;
156 }
157
158 @Override
159 public int hashCode() {
160 return map.hashCode();
161 }
162
163 @Override
164 public String toString() {
165 return "Functions.forMap(" + map + ")";
166 }
167
168 private static final long serialVersionUID = 0;
169 }
170
171 private static class ForMapWithDefault<K, V> implements Function<K, V>, Serializable {
172 final Map<K, ? extends V> map;
173 final @Nullable V defaultValue;
174
175 ForMapWithDefault(Map<K, ? extends V> map, @Nullable V defaultValue) {
176 this.map = checkNotNull(map);
177 this.defaultValue = defaultValue;
178 }
179
180 @Override
181 public V apply(@Nullable K key) {
182 V result = map.get(key);
183 return (result != null || map.containsKey(key)) ? result : defaultValue;
184 }
185
186 @Override
187 public boolean equals(@Nullable Object o) {
188 if (o instanceof ForMapWithDefault) {
189 ForMapWithDefault<?, ?> that = (ForMapWithDefault<?, ?>) o;
190 return map.equals(that.map) && Objects.equal(defaultValue, that.defaultValue);
191 }
192 return false;
193 }
194
195 @Override
196 public int hashCode() {
197 return Objects.hashCode(map, defaultValue);
198 }
199
200 @Override
201 public String toString() {
202 // TODO(cpovirk): maybe remove "defaultValue=" to make this look like the method call does
203 return "Functions.forMap(" + map + ", defaultValue=" + defaultValue + ")";
204 }
205
206 private static final long serialVersionUID = 0;
207 }
208
209 /**
210 * Returns the composition of two functions. For {@code f: A->B} and {@code g: B->C}, composition
211 * is defined as the function h such that {@code h(a) == g(f(a))} for each {@code a}.
212 *
213 * <p><b>Java 8 users:</b> use {@code g.compose(f)} or (probably clearer) {@code f.andThen(g)}
214 * instead.
215 *
216 * @param g the second function to apply
217 * @param f the first function to apply
218 * @return the composition of {@code f} and {@code g}
219 * @see <a href="//en.wikipedia.org/wiki/Function_composition">function composition</a>
220 */
221 public static <A, B, C> Function<A, C> compose(Function<B, C> g, Function<A, ? extends B> f) {
222 return new FunctionComposition<>(g, f);
223 }
224
225 private static class FunctionComposition<A, B, C> implements Function<A, C>, Serializable {
226 private final Function<B, C> g;
227 private final Function<A, ? extends B> f;
228
229 public FunctionComposition(Function<B, C> g, Function<A, ? extends B> f) {
230 this.g = checkNotNull(g);
231 this.f = checkNotNull(f);
232 }
233
234 @Override
235 public C apply(@Nullable A a) {
236 return g.apply(f.apply(a));
237 }
238
239 @Override
240 public boolean equals(@Nullable Object obj) {
241 if (obj instanceof FunctionComposition) {
242 FunctionComposition<?, ?, ?> that = (FunctionComposition<?, ?, ?>) obj;
243 return f.equals(that.f) && g.equals(that.g);
244 }
245 return false;
246 }
247
248 @Override
249 public int hashCode() {
250 return f.hashCode() ^ g.hashCode();
251 }
252
253 @Override
254 public String toString() {
255 // TODO(cpovirk): maybe make this look like the method call does ("Functions.compose(...)")
256 return g + "(" + f + ")";
257 }
258
259 private static final long serialVersionUID = 0;
260 }
261
262 /**
263 * Creates a function that returns the same boolean output as the given predicate for all inputs.
264 *
265 * <p>The returned function is <i>consistent with equals</i> (as documented at {@link
266 * Function#apply}) if and only if {@code predicate} is itself consistent with equals.
267 *
268 * <p><b>Java 8 users:</b> use the method reference {@code predicate::test} instead.
269 */
270 public static <T> Function<T, Boolean> forPredicate(Predicate<T> predicate) {
271 return new PredicateFunction<T>(predicate);
272 }
273
274 /** @see Functions#forPredicate */
275 private static class PredicateFunction<T> implements Function<T, Boolean>, Serializable {
276 private final Predicate<T> predicate;
277
278 private PredicateFunction(Predicate<T> predicate) {
279 this.predicate = checkNotNull(predicate);
280 }
281
282 @Override
283 public Boolean apply(@Nullable T t) {
284 return predicate.apply(t);
285 }
286
287 @Override
288 public boolean equals(@Nullable Object obj) {
289 if (obj instanceof PredicateFunction) {
290 PredicateFunction<?> that = (PredicateFunction<?>) obj;
291 return predicate.equals(that.predicate);
292 }
293 return false;
294 }
295
296 @Override
297 public int hashCode() {
298 return predicate.hashCode();
299 }
300
301 @Override
302 public String toString() {
303 return "Functions.forPredicate(" + predicate + ")";
304 }
305
306 private static final long serialVersionUID = 0;
307 }
308
309 /**
310 * Returns a function that ignores its input and always returns {@code value}.
311 *
312 * <p><b>Java 8 users:</b> use the lambda expression {@code o -> value} instead.
313 *
314 * @param value the constant value for the function to return
315 * @return a function that always returns {@code value}
316 */
317 public static <E> Function<Object, E> constant(@Nullable E value) {
318 return new ConstantFunction<E>(value);
319 }
320
321 private static class ConstantFunction<E> implements Function<Object, E>, Serializable {
322 private final @Nullable E value;
323
324 public ConstantFunction(@Nullable E value) {
325 this.value = value;
326 }
327
328 @Override
329 public E apply(@Nullable Object from) {
330 return value;
331 }
332
333 @Override
334 public boolean equals(@Nullable Object obj) {
335 if (obj instanceof ConstantFunction) {
336 ConstantFunction<?> that = (ConstantFunction<?>) obj;
337 return Objects.equal(value, that.value);
338 }
339 return false;
340 }
341
342 @Override
343 public int hashCode() {
344 return (value == null) ? 0 : value.hashCode();
345 }
346
347 @Override
348 public String toString() {
349 return "Functions.constant(" + value + ")";
350 }
351
352 private static final long serialVersionUID = 0;
353 }
354
355 /**
356 * Returns a function that ignores its input and returns the result of {@code supplier.get()}.
357 *
358 * <p><b>Java 8 users:</b> use the lambda expression {@code o -> supplier.get()} instead.
359 *
360 * @since 10.0
361 */
362 public static <F, T> Function<F, T> forSupplier(Supplier<T> supplier) {
363 return new SupplierFunction<>(supplier);
364 }
365
366 /** @see Functions#forSupplier */
367 private static class SupplierFunction<F, T> implements Function<F, T>, Serializable {
368
369 private final Supplier<T> supplier;
370
371 private SupplierFunction(Supplier<T> supplier) {
372 this.supplier = checkNotNull(supplier);
373 }
374
375 @Override
376 public T apply(@Nullable F input) {
377 return supplier.get();
378 }
379
380 @Override
381 public boolean equals(@Nullable Object obj) {
382 if (obj instanceof SupplierFunction) {
383 SupplierFunction<?, ?> that = (SupplierFunction<?, ?>) obj;
384 return this.supplier.equals(that.supplier);
385 }
386 return false;
387 }
388
389 @Override
390 public int hashCode() {
391 return supplier.hashCode();
392 }
393
394 @Override
395 public String toString() {
396 return "Functions.forSupplier(" + supplier + ")";
397 }
398
399 private static final long serialVersionUID = 0;
400 }
401 }