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    
017    package com.google.common.base;
018    
019    import static com.google.common.base.Preconditions.checkArgument;
020    import static com.google.common.base.Preconditions.checkNotNull;
021    
022    import com.google.common.annotations.Beta;
023    import com.google.common.annotations.GwtCompatible;
024    
025    import java.io.Serializable;
026    import java.util.Map;
027    
028    import 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
044    public 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    }