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 /** 083 * Returns the identity function. 084 * 085 * <p><b>Discouraged:</b> Prefer using a lambda like {@code v -> v}, which is shorter and often 086 * more readable. 087 */ 088 // implementation is "fully variant"; E has become a "pass-through" type 089 @SuppressWarnings("unchecked") 090 public static <E extends @Nullable Object> Function<E, E> identity() { 091 return (Function<E, E>) IdentityFunction.INSTANCE; 092 } 093 094 // enum singleton pattern 095 private enum IdentityFunction implements Function<@Nullable Object, @Nullable Object> { 096 INSTANCE; 097 098 @Override 099 @CheckForNull 100 public Object apply(@CheckForNull Object o) { 101 return o; 102 } 103 104 @Override 105 public String toString() { 106 return "Functions.identity()"; 107 } 108 } 109 110 /** 111 * Returns a function which performs a map lookup. The returned function throws an {@link 112 * IllegalArgumentException} if given a key that does not exist in the map. See also {@link 113 * #forMap(Map, Object)}, which returns a default value in this case. 114 * 115 * <p>Note: if {@code map} is a {@link com.google.common.collect.BiMap BiMap} (or can be one), you 116 * can use {@link com.google.common.collect.Maps#asConverter Maps.asConverter} instead to get a 117 * function that also supports reverse conversion. 118 * 119 * <p><b>Java 8 users:</b> if you are okay with {@code null} being returned for an unrecognized 120 * key (instead of an exception being thrown), you can use the method reference {@code map::get} 121 * instead. 122 */ 123 public static <K extends @Nullable Object, V extends @Nullable Object> Function<K, V> forMap( 124 Map<K, V> map) { 125 return new FunctionForMapNoDefault<>(map); 126 } 127 128 /** 129 * Returns a function which performs a map lookup with a default value. The function created by 130 * this method returns {@code defaultValue} for all inputs that do not belong to the map's key 131 * set. See also {@link #forMap(Map)}, which throws an exception in this case. 132 * 133 * <p><b>Java 8 users:</b> you can just write the lambda expression {@code k -> 134 * map.getOrDefault(k, defaultValue)} instead. 135 * 136 * @param map source map that determines the function behavior 137 * @param defaultValue the value to return for inputs that aren't map keys 138 * @return function that returns {@code map.get(a)} when {@code a} is a key, or {@code 139 * defaultValue} otherwise 140 */ 141 public static <K extends @Nullable Object, V extends @Nullable Object> Function<K, V> forMap( 142 Map<K, ? extends V> map, @ParametricNullness V defaultValue) { 143 return new ForMapWithDefault<>(map, defaultValue); 144 } 145 146 private static class FunctionForMapNoDefault< 147 K extends @Nullable Object, V extends @Nullable Object> 148 implements Function<K, V>, Serializable { 149 final Map<K, V> map; 150 151 FunctionForMapNoDefault(Map<K, V> map) { 152 this.map = checkNotNull(map); 153 } 154 155 @Override 156 @ParametricNullness 157 public V apply(@ParametricNullness K key) { 158 V result = map.get(key); 159 checkArgument(result != null || map.containsKey(key), "Key '%s' not present in map", key); 160 // The unchecked cast is safe because of the containsKey check. 161 return uncheckedCastNullableTToT(result); 162 } 163 164 @Override 165 public boolean equals(@CheckForNull Object o) { 166 if (o instanceof FunctionForMapNoDefault) { 167 FunctionForMapNoDefault<?, ?> that = (FunctionForMapNoDefault<?, ?>) o; 168 return map.equals(that.map); 169 } 170 return false; 171 } 172 173 @Override 174 public int hashCode() { 175 return map.hashCode(); 176 } 177 178 @Override 179 public String toString() { 180 return "Functions.forMap(" + map + ")"; 181 } 182 183 private static final long serialVersionUID = 0; 184 } 185 186 private static class ForMapWithDefault<K extends @Nullable Object, V extends @Nullable Object> 187 implements Function<K, V>, Serializable { 188 final Map<K, ? extends V> map; 189 @ParametricNullness final V defaultValue; 190 191 ForMapWithDefault(Map<K, ? extends V> map, @ParametricNullness V defaultValue) { 192 this.map = checkNotNull(map); 193 this.defaultValue = defaultValue; 194 } 195 196 @Override 197 @ParametricNullness 198 public V apply(@ParametricNullness K key) { 199 V result = map.get(key); 200 // The unchecked cast is safe because of the containsKey check. 201 return (result != null || map.containsKey(key)) 202 ? uncheckedCastNullableTToT(result) 203 : defaultValue; 204 } 205 206 @Override 207 public boolean equals(@CheckForNull Object o) { 208 if (o instanceof ForMapWithDefault) { 209 ForMapWithDefault<?, ?> that = (ForMapWithDefault<?, ?>) o; 210 return map.equals(that.map) && Objects.equal(defaultValue, that.defaultValue); 211 } 212 return false; 213 } 214 215 @Override 216 public int hashCode() { 217 return Objects.hashCode(map, defaultValue); 218 } 219 220 @Override 221 public String toString() { 222 // TODO(cpovirk): maybe remove "defaultValue=" to make this look like the method call does 223 return "Functions.forMap(" + map + ", defaultValue=" + defaultValue + ")"; 224 } 225 226 private static final long serialVersionUID = 0; 227 } 228 229 /** 230 * Returns the composition of two functions. For {@code f: A->B} and {@code g: B->C}, composition 231 * is defined as the function h such that {@code h(a) == g(f(a))} for each {@code a}. 232 * 233 * <p><b>Java 8 users:</b> use {@code g.compose(f)} or (probably clearer) {@code f.andThen(g)} 234 * instead. 235 * 236 * @param g the second function to apply 237 * @param f the first function to apply 238 * @return the composition of {@code f} and {@code g} 239 * @see <a href="//en.wikipedia.org/wiki/Function_composition">function composition</a> 240 */ 241 public static <A extends @Nullable Object, B extends @Nullable Object, C extends @Nullable Object> 242 Function<A, C> compose(Function<B, C> g, Function<A, ? extends B> f) { 243 return new FunctionComposition<>(g, f); 244 } 245 246 private static class FunctionComposition< 247 A extends @Nullable Object, B extends @Nullable Object, C extends @Nullable Object> 248 implements Function<A, C>, Serializable { 249 private final Function<B, C> g; 250 private final Function<A, ? extends B> f; 251 252 public FunctionComposition(Function<B, C> g, Function<A, ? extends B> f) { 253 this.g = checkNotNull(g); 254 this.f = checkNotNull(f); 255 } 256 257 @Override 258 @ParametricNullness 259 public C apply(@ParametricNullness A a) { 260 return g.apply(f.apply(a)); 261 } 262 263 @Override 264 public boolean equals(@CheckForNull Object obj) { 265 if (obj instanceof FunctionComposition) { 266 FunctionComposition<?, ?, ?> that = (FunctionComposition<?, ?, ?>) obj; 267 return f.equals(that.f) && g.equals(that.g); 268 } 269 return false; 270 } 271 272 @Override 273 public int hashCode() { 274 return f.hashCode() ^ g.hashCode(); 275 } 276 277 @Override 278 public String toString() { 279 // TODO(cpovirk): maybe make this look like the method call does ("Functions.compose(...)") 280 return g + "(" + f + ")"; 281 } 282 283 private static final long serialVersionUID = 0; 284 } 285 286 /** 287 * Creates a function that returns the same boolean output as the given predicate for all inputs. 288 * 289 * <p>The returned function is <i>consistent with equals</i> (as documented at {@link 290 * Function#apply}) if and only if {@code predicate} is itself consistent with equals. 291 * 292 * <p><b>Java 8 users:</b> use the method reference {@code predicate::test} instead. 293 */ 294 public static <T extends @Nullable Object> Function<T, Boolean> forPredicate( 295 Predicate<T> predicate) { 296 return new PredicateFunction<>(predicate); 297 } 298 299 /** @see Functions#forPredicate */ 300 private static class PredicateFunction<T extends @Nullable Object> 301 implements Function<T, Boolean>, Serializable { 302 private final Predicate<T> predicate; 303 304 private PredicateFunction(Predicate<T> predicate) { 305 this.predicate = checkNotNull(predicate); 306 } 307 308 @Override 309 public Boolean apply(@ParametricNullness T t) { 310 return predicate.apply(t); 311 } 312 313 @Override 314 public boolean equals(@CheckForNull Object obj) { 315 if (obj instanceof PredicateFunction) { 316 PredicateFunction<?> that = (PredicateFunction<?>) obj; 317 return predicate.equals(that.predicate); 318 } 319 return false; 320 } 321 322 @Override 323 public int hashCode() { 324 return predicate.hashCode(); 325 } 326 327 @Override 328 public String toString() { 329 return "Functions.forPredicate(" + predicate + ")"; 330 } 331 332 private static final long serialVersionUID = 0; 333 } 334 335 /** 336 * Returns a function that ignores its input and always returns {@code value}. 337 * 338 * <p><b>Java 8 users:</b> use the lambda expression {@code o -> value} instead. 339 * 340 * @param value the constant value for the function to return 341 * @return a function that always returns {@code value} 342 */ 343 public static <E extends @Nullable Object> Function<@Nullable Object, E> constant( 344 @ParametricNullness E value) { 345 return new ConstantFunction<>(value); 346 } 347 348 private static class ConstantFunction<E extends @Nullable Object> 349 implements Function<@Nullable Object, E>, Serializable { 350 @ParametricNullness private final E value; 351 352 public ConstantFunction(@ParametricNullness E value) { 353 this.value = value; 354 } 355 356 @Override 357 @ParametricNullness 358 public E apply(@CheckForNull Object from) { 359 return value; 360 } 361 362 @Override 363 public boolean equals(@CheckForNull Object obj) { 364 if (obj instanceof ConstantFunction) { 365 ConstantFunction<?> that = (ConstantFunction<?>) obj; 366 return Objects.equal(value, that.value); 367 } 368 return false; 369 } 370 371 @Override 372 public int hashCode() { 373 return (value == null) ? 0 : value.hashCode(); 374 } 375 376 @Override 377 public String toString() { 378 return "Functions.constant(" + value + ")"; 379 } 380 381 private static final long serialVersionUID = 0; 382 } 383 384 /** 385 * Returns a function that ignores its input and returns the result of {@code supplier.get()}. 386 * 387 * <p><b>Java 8 users:</b> use the lambda expression {@code o -> supplier.get()} instead. 388 * 389 * @since 10.0 390 */ 391 public static <F extends @Nullable Object, T extends @Nullable Object> Function<F, T> forSupplier( 392 Supplier<T> supplier) { 393 return new SupplierFunction<>(supplier); 394 } 395 396 /** @see Functions#forSupplier */ 397 private static class SupplierFunction<F extends @Nullable Object, T extends @Nullable Object> 398 implements Function<F, T>, Serializable { 399 400 private final Supplier<T> supplier; 401 402 private SupplierFunction(Supplier<T> supplier) { 403 this.supplier = checkNotNull(supplier); 404 } 405 406 @Override 407 @ParametricNullness 408 public T apply(@ParametricNullness F input) { 409 return supplier.get(); 410 } 411 412 @Override 413 public boolean equals(@CheckForNull Object obj) { 414 if (obj instanceof SupplierFunction) { 415 SupplierFunction<?, ?> that = (SupplierFunction<?, ?>) obj; 416 return this.supplier.equals(that.supplier); 417 } 418 return false; 419 } 420 421 @Override 422 public int hashCode() { 423 return supplier.hashCode(); 424 } 425 426 @Override 427 public String toString() { 428 return "Functions.forSupplier(" + supplier + ")"; 429 } 430 431 private static final long serialVersionUID = 0; 432 } 433}