@Beta @GwtCompatible public abstract class Converter<A,B> extends Object implements Function<A,B>, ConverterNullable<A,B>
A function from A to B with an associated reverse function from B to A; used for converting back and forth between different representations of the same information.
The reverse operation may be a strict inverse (meaning that converter.reverse().convert(converter.convert(a)).equals(a) is always true). However, it is very common (perhaps more common) for round-trip conversion to be lossy. Consider an example round-trip using Doubles.stringConverter():
stringConverter().convert("1.00") returns the Double value 1.0
stringConverter().reverse().convert(1.0) returns the string "1.0" --
not the same string ("1.00") we started with
Note that it should still be the case that the round-tripped and original objects are similar.
A converter always converts null to null and non-null references to non-null references. It would not make sense to consider null and a non-null reference to be “different representations of the same information”, since one is distinguishable from missing information and the other is not. The convert(A) method handles this null behavior for all converters; implementations of doForward(A) and doBackward(B) are guaranteed to never be passed null, and must never return null.
For users who wish for any behavior around nulls, see ConverterNullable. Because Converter guarantees graceful mapping of null to null, it can safely implement ConverterNullable.
Getting a converter:
Enums.stringConverter(java.lang.Class<T>), Ints.stringConverter or the reverse views of these.
Maps.asConverter. For example, use this to create
a "fake" converter for a unit test. It is unnecessary (and confusing) to mock the
Converter type using a mocking framework.
doForward(A) and doBackward(B) methods.
from(java.util.function.Function<? super A, ? extends B>, java.util.function.Function<? super B, ? extends A>).
Using a converter:
converter.convert(a).
converter.convertAll(as).
converter.reverse().convert(b) or converter.reverse().convertAll(bs).
converter or converter.reverse() anywhere a Function is accepted
doForward(A) or doBackward(B) directly; these exist only to be
overridden.
{@code
return new Converter<Integer, String>() {
| Modifier | Constructor and Description |
|---|---|
protected |
Converter()
Constructor for use by subclasses.
|
| Modifier and Type | Method and Description |
|---|---|
<C> Converter<A,C> |
andThen(Converter<B,C> secondConverter)
Returns a converter whose
convert method applies secondConverter to the result of this converter. |
B |
apply(A a)
Deprecated.
Provided to satisfy the
Function interface; use convert(A) instead. |
B |
convert(A a)
Returns a representation of
a as an instance of type B. |
Iterable<B> |
convertAll(Iterable<? extends A> fromIterable)
Returns an iterable that applies
convert to each element of fromIterable. |
B |
convertNonNull(A a)
Returns a representation of
a as an instance of type B, using the type system (and not null checks) to ensure that input and output are non-null. |
protected abstract A |
doBackward(B b)
Returns a representation of
b as an instance of type A. |
protected abstract B |
doForward(A a)
Returns a representation of
a as an instance of type B. |
boolean |
equals(Object object)
Indicates whether another object is equal to this converter.
|
static <A,B> Converter<A,B> |
from(Function<? super A,? extends B> forwardFunction,
Function<? super B,? extends A> backwardFunction)
Returns a converter based on existing forward and backward functions.
|
static <A,B> Converter<A,B> |
from(Function<? super A,? extends B> forwardFunction,
Function<? super B,? extends A> backwardFunction,
String name)
Returns a converter based on existing forward and backward functions.
|
static <T> Converter<T,T> |
identity()
Returns a serializable converter that always converts or reverses an object to itself.
|
Converter<B,A> |
reverse()
Returns the reversed view of this converter, which converts
this.convert(a) back to a value roughly equivalent to a. |
A |
revert(B b)
Returns a representation of
b as an instance of type A. |
A |
revertNonNull(B b)
Returns a representation of
b as an instance of type A, using the type system (and not null checks) to ensure that input and output are non-null. |
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitandThenprotected abstract B doForward(A a)
Returns a representation of a as an instance of type B. If a cannot be converted, an unchecked exception (such as IllegalArgumentException) should be thrown.
a - the instance to convert; will never be nullprotected abstract A doBackward(B b)
Returns a representation of b as an instance of type A. If b cannot be converted, an unchecked exception (such as IllegalArgumentException) should be thrown.
b - the instance to convert; will never be nullUnsupportedOperationException - if backward conversion is not implemented; this should be very rare. Note that if backward conversion is not only unimplemented but unimplementable (for example, consider a Converter<Chicken, ChickenNugget>), then this is not logically a Converter at all, and should just implement Function.@Nullable public final B convert(@Nullable A a)
Returns a representation of a as an instance of type B.
convert in interface ConverterNullable<A,B>a - the instance to convert; possibly nulla is null@Nullable public final A revert(@Nullable B b)
Returns a representation of b as an instance of type A.
revert in interface ConverterNullable<A,B>b - the instance to convert; possibly nullb is nullpublic final B convertNonNull(A a)
Returns a representation of a as an instance of type B, using the type system (and not null checks) to ensure that input and output are non-null.
public final A revertNonNull(B b)
Returns a representation of b as an instance of type A, using the type system (and not null checks) to ensure that input and output are non-null.
public Iterable<B> convertAll(Iterable<? extends A> fromIterable)
Returns an iterable that applies convert to each element of fromIterable. The conversion is done lazily.
The returned iterable’s iterator supports remove() if the input iterator does. After a successful remove() call, fromIterable no longer contains the corresponding element.
convertAll in interface ConverterNullable<A,B>public Converter<B,A> reverse()
Returns the reversed view of this converter, which converts this.convert(a) back to a value roughly equivalent to a.
The returned converter is serializable if this converter is.
reverse in interface ConverterNullable<A,B>public final <C> Converter<A,C> andThen(Converter<B,C> secondConverter)
Returns a converter whose convert method applies secondConverter to the result of this converter. Its reverse method applies the converters in reverse order.
The returned converter is serializable if this converter and secondConverter are.
@Deprecated @Nullable public final B apply(@Nullable A a)
Function interface; use convert(A) instead.public boolean equals(@Nullable Object object)
Indicates whether another object is equal to this converter.
Most implementations will have no reason to override the behavior of Object.equals(java.lang.Object). However, an implementation may also choose to return true whenever object is a Converter that it considers interchangeable with this one. “Interchangeable” typically means that Objects.equals(this.convert(a), that.convert(a)) is true for all a of type A (and similarly for reverse). Note that a false result from this method does not imply that the converters are known not to be interchangeable.
public static <A,B> Converter<A,B> from(Function<? super A,? extends B> forwardFunction, Function<? super B,? extends A> backwardFunction)
Returns a converter based on existing forward and backward functions. Note that it is unnecessary to create new classes implementing Function just to pass them in here. Instead, simply subclass Converter and implement its doForward(A) and doBackward(B) methods directly.
These functions will never be passed null and must not under any circumstances return null. If a value cannot be converted, the function should throw an unchecked exception (typically, but not necessarily, IllegalArgumentException).
The returned converter is serializable if both provided functions are.
from in interface ConverterNullable<A,B>public static <A,B> Converter<A,B> from(Function<? super A,? extends B> forwardFunction, Function<? super B,? extends A> backwardFunction, String name)
Returns a converter based on existing forward and backward functions. Note that it is unnecessary to create new classes implementing Function just to pass them in here. Instead, simply subclass Converter and implement its doForward(A) and doBackward(B) methods directly.
These functions will never be passed null and must not under any circumstances return null. If a value cannot be converted, the function should throw an unchecked exception (typically, but not necessarily, IllegalArgumentException).
The name parameter will be returned as the result of Object.toString().
The returned converter is serializable if both provided functions are.
from in interface ConverterNullable<A,B>