View Javadoc
1   /*
2    * Copyright (C) 2008 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.checkNotNull;
18  
19  import com.google.common.annotations.GwtCompatible;
20  import com.google.errorprone.annotations.CanIgnoreReturnValue;
21  import com.google.errorprone.annotations.ForOverride;
22  import com.google.errorprone.annotations.concurrent.LazyInit;
23  import java.io.Serializable;
24  import java.util.Iterator;
25  import javax.annotation.Nullable;
26  
27  /**
28   * A function from {@code A} to {@code B} with an associated <i>reverse</i> function from {@code B}
29   * to {@code A}; used for converting back and forth between <i>different representations of the same
30   * information</i>.
31   *
32   * <h3>Invertibility</h3>
33   *
34   * <p>The reverse operation <b>may</b> be a strict <i>inverse</i> (meaning that {@code
35   * converter.reverse().convert(converter.convert(a)).equals(a)} is always true). However, it is very
36   * common (perhaps <i>more</i> common) for round-trip conversion to be <i>lossy</i>. Consider an
37   * example round-trip using {@link com.google.common.primitives.Doubles#stringConverter}:
38   *
39   * <ol>
40   * <li>{@code stringConverter().convert("1.00")} returns the {@code Double} value {@code 1.0}
41   * <li>{@code stringConverter().reverse().convert(1.0)} returns the string {@code "1.0"} --
42   *     <i>not</i> the same string ({@code "1.00"}) we started with
43   * </ol>
44   *
45   * <p>Note that it should still be the case that the round-tripped and original objects are
46   * <i>similar</i>.
47   *
48   * <h3>Nullability</h3>
49   *
50   * <p>A converter always converts {@code null} to {@code null} and non-null references to non-null
51   * references. It would not make sense to consider {@code null} and a non-null reference to be
52   * "different representations of the same information", since one is distinguishable from
53   * <i>missing</i> information and the other is not. The {@link #convert} method handles this null
54   * behavior for all converters; implementations of {@link #doForward} and {@link #doBackward} are
55   * guaranteed to never be passed {@code null}, and must never return {@code null}.
56   *
57   *
58   * <h3>Common ways to use</h3>
59   *
60   * <p>Getting a converter:
61   *
62   * <ul>
63   * <li>Use a provided converter implementation, such as {@link Enums#stringConverter}, {@link
64   *     com.google.common.primitives.Ints#stringConverter Ints.stringConverter} or the {@linkplain
65   *     #reverse reverse} views of these.
66   * <li>Convert between specific preset values using {@link
67   *     com.google.common.collect.Maps#asConverter Maps.asConverter}. For example, use this to create
68   *     a "fake" converter for a unit test. It is unnecessary (and confusing) to <i>mock</i> the
69   *     {@code Converter} type using a mocking framework.
70   * <li>Extend this class and implement its {@link #doForward} and {@link #doBackward} methods.
71   * <li><b>Java 8 users:</b> you may prefer to pass two lambda expressions or method references to
72   *     the {@link #from from} factory method.
73   * </ul>
74   *
75   * <p>Using a converter:
76   *
77   * <ul>
78   * <li>Convert one instance in the "forward" direction using {@code converter.convert(a)}.
79   * <li>Convert multiple instances "forward" using {@code converter.convertAll(as)}.
80   * <li>Convert in the "backward" direction using {@code converter.reverse().convert(b)} or {@code
81   *     converter.reverse().convertAll(bs)}.
82   * <li>Use {@code converter} or {@code converter.reverse()} anywhere a {@link
83   *     java.util.function.Function} is accepted (for example {@link java.util.stream.Stream#map
84   *     Stream.map}).
85   * <li><b>Do not</b> call {@link #doForward} or {@link #doBackward} directly; these exist only to be
86   *     overridden.
87   * </ul>
88   *
89   * <h3>Example</h3>
90   *
91   * <pre>
92   *   return new Converter&lt;Integer, String&gt;() {
93   *     protected String doForward(Integer i) {
94   *       return Integer.toHexString(i);
95   *     }
96   *
97   *     protected Integer doBackward(String s) {
98   *       return parseUnsignedInt(s, 16);
99   *     }
100  *   };</pre>
101  *
102  * <p>An alternative using Java 8:
103  *
104  * <pre>{@code
105  * return Converter.from(
106  *     Integer::toHexString,
107  *     s -> parseUnsignedInt(s, 16));
108  * }</pre>
109  *
110  * @author Mike Ward
111  * @author Kurt Alfred Kluever
112  * @author Gregory Kick
113  * @since 16.0
114  */
115 @GwtCompatible
116 public abstract class Converter<A, B> implements Function<A, B> {
117   private final boolean handleNullAutomatically;
118 
119   // We lazily cache the reverse view to avoid allocating on every call to reverse().
120   @LazyInit
121   private transient Converter<B, A> reverse;
122 
123   /** Constructor for use by subclasses. */
124   protected Converter() {
125     this(true);
126   }
127 
128   /**
129    * Constructor used only by {@code LegacyConverter} to suspend automatic null-handling.
130    */
131   Converter(boolean handleNullAutomatically) {
132     this.handleNullAutomatically = handleNullAutomatically;
133   }
134 
135   // SPI methods (what subclasses must implement)
136 
137   /**
138    * Returns a representation of {@code a} as an instance of type {@code B}. If {@code a} cannot be
139    * converted, an unchecked exception (such as {@link IllegalArgumentException}) should be thrown.
140    *
141    * @param a the instance to convert; will never be null
142    * @return the converted instance; <b>must not</b> be null
143    */
144   @ForOverride
145   protected abstract B doForward(A a);
146 
147   /**
148    * Returns a representation of {@code b} as an instance of type {@code A}. If {@code b} cannot be
149    * converted, an unchecked exception (such as {@link IllegalArgumentException}) should be thrown.
150    *
151    * @param b the instance to convert; will never be null
152    * @return the converted instance; <b>must not</b> be null
153    * @throws UnsupportedOperationException if backward conversion is not implemented; this should be
154    *     very rare. Note that if backward conversion is not only unimplemented but
155    *     unimplement<i>able</i> (for example, consider a {@code Converter<Chicken, ChickenNugget>}),
156    *     then this is not logically a {@code Converter} at all, and should just implement {@link
157    *     Function}.
158    */
159   @ForOverride
160   protected abstract A doBackward(B b);
161 
162   // API (consumer-side) methods
163 
164   /**
165    * Returns a representation of {@code a} as an instance of type {@code B}.
166    *
167    * @return the converted value; is null <i>if and only if</i> {@code a} is null
168    */
169   @Nullable
170   @CanIgnoreReturnValue
171   public final B convert(@Nullable A a) {
172     return correctedDoForward(a);
173   }
174 
175   @Nullable
176   B correctedDoForward(@Nullable A a) {
177     if (handleNullAutomatically) {
178       // TODO(kevinb): we shouldn't be checking for a null result at runtime. Assert?
179       return a == null ? null : checkNotNull(doForward(a));
180     } else {
181       return doForward(a);
182     }
183   }
184 
185   @Nullable
186   A correctedDoBackward(@Nullable B b) {
187     if (handleNullAutomatically) {
188       // TODO(kevinb): we shouldn't be checking for a null result at runtime. Assert?
189       return b == null ? null : checkNotNull(doBackward(b));
190     } else {
191       return doBackward(b);
192     }
193   }
194 
195   /**
196    * Returns an iterable that applies {@code convert} to each element of {@code fromIterable}. The
197    * conversion is done lazily.
198    *
199    * <p>The returned iterable's iterator supports {@code remove()} if the input iterator does. After
200    * a successful {@code remove()} call, {@code fromIterable} no longer contains the corresponding
201    * element.
202    */
203   @CanIgnoreReturnValue
204   public Iterable<B> convertAll(final Iterable<? extends A> fromIterable) {
205     checkNotNull(fromIterable, "fromIterable");
206     return new Iterable<B>() {
207       @Override
208       public Iterator<B> iterator() {
209         return new Iterator<B>() {
210           private final Iterator<? extends A> fromIterator = fromIterable.iterator();
211 
212           @Override
213           public boolean hasNext() {
214             return fromIterator.hasNext();
215           }
216 
217           @Override
218           public B next() {
219             return convert(fromIterator.next());
220           }
221 
222           @Override
223           public void remove() {
224             fromIterator.remove();
225           }
226         };
227       }
228     };
229   }
230 
231   /**
232    * Returns the reversed view of this converter, which converts {@code this.convert(a)} back to a
233    * value roughly equivalent to {@code a}.
234    *
235    * <p>The returned converter is serializable if {@code this} converter is.
236    *
237    * <p><b>Note:</b> you should not override this method. It is non-final for legacy reasons.
238    */
239   @CanIgnoreReturnValue
240   public Converter<B, A> reverse() {
241     Converter<B, A> result = reverse;
242     return (result == null) ? reverse = new ReverseConverter<>(this) : result;
243   }
244 
245   private static final class ReverseConverter<A, B> extends Converter<B, A>
246       implements Serializable {
247     final Converter<A, B> original;
248 
249     ReverseConverter(Converter<A, B> original) {
250       this.original = original;
251     }
252 
253     /*
254      * These gymnastics are a little confusing. Basically this class has neither legacy nor
255      * non-legacy behavior; it just needs to let the behavior of the backing converter shine
256      * through. So, we override the correctedDo* methods, after which the do* methods should never
257      * be reached.
258      */
259 
260     @Override
261     protected A doForward(B b) {
262       throw new AssertionError();
263     }
264 
265     @Override
266     protected B doBackward(A a) {
267       throw new AssertionError();
268     }
269 
270     @Override
271     @Nullable
272     A correctedDoForward(@Nullable B b) {
273       return original.correctedDoBackward(b);
274     }
275 
276     @Override
277     @Nullable
278     B correctedDoBackward(@Nullable A a) {
279       return original.correctedDoForward(a);
280     }
281 
282     @Override
283     public Converter<A, B> reverse() {
284       return original;
285     }
286 
287     @Override
288     public boolean equals(@Nullable Object object) {
289       if (object instanceof ReverseConverter) {
290         ReverseConverter<?, ?> that = (ReverseConverter<?, ?>) object;
291         return this.original.equals(that.original);
292       }
293       return false;
294     }
295 
296     @Override
297     public int hashCode() {
298       return ~original.hashCode();
299     }
300 
301     @Override
302     public String toString() {
303       return original + ".reverse()";
304     }
305 
306     private static final long serialVersionUID = 0L;
307   }
308 
309   /**
310    * Returns a converter whose {@code convert} method applies {@code secondConverter} to the result
311    * of this converter. Its {@code reverse} method applies the converters in reverse order.
312    *
313    * <p>The returned converter is serializable if {@code this} converter and {@code secondConverter}
314    * are.
315    */
316   public final <C> Converter<A, C> andThen(Converter<B, C> secondConverter) {
317     return doAndThen(secondConverter);
318   }
319 
320   /**
321    * Package-private non-final implementation of andThen() so only we can override it.
322    */
323   <C> Converter<A, C> doAndThen(Converter<B, C> secondConverter) {
324     return new ConverterComposition<>(this, checkNotNull(secondConverter));
325   }
326 
327   private static final class ConverterComposition<A, B, C> extends Converter<A, C>
328       implements Serializable {
329     final Converter<A, B> first;
330     final Converter<B, C> second;
331 
332     ConverterComposition(Converter<A, B> first, Converter<B, C> second) {
333       this.first = first;
334       this.second = second;
335     }
336 
337     /*
338      * These gymnastics are a little confusing. Basically this class has neither legacy nor
339      * non-legacy behavior; it just needs to let the behaviors of the backing converters shine
340      * through (which might even differ from each other!). So, we override the correctedDo* methods,
341      * after which the do* methods should never be reached.
342      */
343 
344     @Override
345     protected C doForward(A a) {
346       throw new AssertionError();
347     }
348 
349     @Override
350     protected A doBackward(C c) {
351       throw new AssertionError();
352     }
353 
354     @Override
355     @Nullable
356     C correctedDoForward(@Nullable A a) {
357       return second.correctedDoForward(first.correctedDoForward(a));
358     }
359 
360     @Override
361     @Nullable
362     A correctedDoBackward(@Nullable C c) {
363       return first.correctedDoBackward(second.correctedDoBackward(c));
364     }
365 
366     @Override
367     public boolean equals(@Nullable Object object) {
368       if (object instanceof ConverterComposition) {
369         ConverterComposition<?, ?, ?> that = (ConverterComposition<?, ?, ?>) object;
370         return this.first.equals(that.first) && this.second.equals(that.second);
371       }
372       return false;
373     }
374 
375     @Override
376     public int hashCode() {
377       return 31 * first.hashCode() + second.hashCode();
378     }
379 
380     @Override
381     public String toString() {
382       return first + ".andThen(" + second + ")";
383     }
384 
385     private static final long serialVersionUID = 0L;
386   }
387 
388   /**
389    * @deprecated Provided to satisfy the {@code Function} interface; use {@link #convert} instead.
390    */
391   @Deprecated
392   @Override
393   @Nullable
394   @CanIgnoreReturnValue
395   public final B apply(@Nullable A a) {
396     return convert(a);
397   }
398 
399   /**
400    * Indicates whether another object is equal to this converter.
401    *
402    * <p>Most implementations will have no reason to override the behavior of {@link Object#equals}.
403    * However, an implementation may also choose to return {@code true} whenever {@code object} is a
404    * {@link Converter} that it considers <i>interchangeable</i> with this one. "Interchangeable"
405    * <i>typically</i> means that {@code Objects.equal(this.convert(a), that.convert(a))} is true for
406    * all {@code a} of type {@code A} (and similarly for {@code reverse}). Note that a {@code false}
407    * result from this method does not imply that the converters are known <i>not</i> to be
408    * interchangeable.
409    */
410   @Override
411   public boolean equals(@Nullable Object object) {
412     return super.equals(object);
413   }
414 
415   // Static converters
416 
417   /**
418    * Returns a converter based on separate forward and backward functions. This is useful if the
419    * function instances already exist, or so that you can supply lambda expressions. If those
420    * circumstances don't apply, you probably don't need to use this; subclass {@code Converter} and
421    * implement its {@link #doForward} and {@link #doBackward} methods directly.
422    *
423    * <p>These functions will never be passed {@code null} and must not under any circumstances
424    * return {@code null}. If a value cannot be converted, the function should throw an unchecked
425    * exception (typically, but not necessarily, {@link IllegalArgumentException}).
426    *
427    * <p>The returned converter is serializable if both provided functions are.
428    *
429    * @since 17.0
430    */
431   public static <A, B> Converter<A, B> from(
432       Function<? super A, ? extends B> forwardFunction,
433       Function<? super B, ? extends A> backwardFunction) {
434     return new FunctionBasedConverter<>(forwardFunction, backwardFunction);
435   }
436 
437   private static final class FunctionBasedConverter<A, B> extends Converter<A, B>
438       implements Serializable {
439     private final Function<? super A, ? extends B> forwardFunction;
440     private final Function<? super B, ? extends A> backwardFunction;
441 
442     private FunctionBasedConverter(
443         Function<? super A, ? extends B> forwardFunction,
444         Function<? super B, ? extends A> backwardFunction) {
445       this.forwardFunction = checkNotNull(forwardFunction);
446       this.backwardFunction = checkNotNull(backwardFunction);
447     }
448 
449     @Override
450     protected B doForward(A a) {
451       return forwardFunction.apply(a);
452     }
453 
454     @Override
455     protected A doBackward(B b) {
456       return backwardFunction.apply(b);
457     }
458 
459     @Override
460     public boolean equals(@Nullable Object object) {
461       if (object instanceof FunctionBasedConverter) {
462         FunctionBasedConverter<?, ?> that = (FunctionBasedConverter<?, ?>) object;
463         return this.forwardFunction.equals(that.forwardFunction)
464             && this.backwardFunction.equals(that.backwardFunction);
465       }
466       return false;
467     }
468 
469     @Override
470     public int hashCode() {
471       return forwardFunction.hashCode() * 31 + backwardFunction.hashCode();
472     }
473 
474     @Override
475     public String toString() {
476       return "Converter.from(" + forwardFunction + ", " + backwardFunction + ")";
477     }
478   }
479 
480   /**
481    * Returns a serializable converter that always converts or reverses an object to itself.
482    */
483   @SuppressWarnings("unchecked") // implementation is "fully variant"
484   public static <T> Converter<T, T> identity() {
485     return (IdentityConverter<T>) IdentityConverter.INSTANCE;
486   }
487 
488   /**
489    * A converter that always converts or reverses an object to itself. Note that T is now a
490    * "pass-through type".
491    */
492   private static final class IdentityConverter<T> extends Converter<T, T> implements Serializable {
493     static final IdentityConverter INSTANCE = new IdentityConverter();
494 
495     @Override
496     protected T doForward(T t) {
497       return t;
498     }
499 
500     @Override
501     protected T doBackward(T t) {
502       return t;
503     }
504 
505     @Override
506     public IdentityConverter<T> reverse() {
507       return this;
508     }
509 
510     @Override
511     <S> Converter<T, S> doAndThen(Converter<T, S> otherConverter) {
512       return checkNotNull(otherConverter, "otherConverter");
513     }
514 
515     /*
516      * We *could* override convertAll() to return its input, but it's a rather pointless
517      * optimization and opened up a weird type-safety problem.
518      */
519 
520     @Override
521     public String toString() {
522       return "Converter.identity()";
523     }
524 
525     private Object readResolve() {
526       return INSTANCE;
527     }
528 
529     private static final long serialVersionUID = 0L;
530   }
531 }