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