@GwtCompatible public abstract class Converter<A,B> extends Object implements Function<A,B>
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
.
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
factory method.
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 (for example Stream#map
).
doForward(A)
or doBackward(B)
directly; these exist only to be
overridden.
return new Converter<Integer, String>() { protected String doForward(Integer i) { return Integer.toHexString(i); } protected Integer doBackward(String s) { return parseUnsignedInt(s, 16); } };
An alternative using Java 8:
return Converter.from(
Integer::toHexString,
s -> parseUnsignedInt(s, 16));
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 . |
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 separate 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 . |
protected Converter()
protected abstract B doForward(A a)
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)
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)
a
as an instance of type B
.a
is nullpublic Iterable<B> convertAll(Iterable<? extends A> fromIterable)
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.
public Converter<B,A> reverse()
this.convert(a)
back to a
value roughly equivalent to a
.
The returned converter is serializable if this
converter is.
Note: you should not override this method. It is non-final for legacy reasons.
public final <C> Converter<A,C> andThen(Converter<B,C> secondConverter)
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)
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.equal(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)
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.
Copyright © 2010-2017. All Rights Reserved.