Class Converter<A,B>
- java.lang.Object
-
- com.google.common.base.Converter<A,B>
-
- All Implemented Interfaces:
Function<A,B>
@GwtCompatible public abstract class Converter<A,B> extends Object implements Function<A,B>
A function fromA
toB
with an associated reverse function fromB
toA
; used for converting back and forth between different representations of the same information.Invertibility
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 usingDoubles.stringConverter()
:stringConverter().convert("1.00")
returns theDouble
value1.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.
Nullability
A converter always converts
null
tonull
and non-null references to non-null references. It would not make sense to considernull
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. Theconvert(A)
method handles this null behavior for all converters; implementations ofdoForward(A)
anddoBackward(B)
are guaranteed to never be passednull
, and must never returnnull
.Common ways to use
Getting a converter:
- Use a provided converter implementation, such as
Enums.stringConverter(java.lang.Class<T>)
,Ints.stringConverter
or the reverse views of these. - Convert between specific preset values using
Maps.asConverter
. For example, use this to create a "fake" converter for a unit test. It is unnecessary (and confusing) to mock theConverter
type using a mocking framework. - Extend this class and implement its
doForward(A)
anddoBackward(B)
methods. - Java 8 users: you may prefer to pass two lambda expressions or method references to
the
from
factory method.
Using a converter:
- Convert one instance in the "forward" direction using
converter.convert(a)
. - Convert multiple instances "forward" using
converter.convertAll(as)
. - Convert in the "backward" direction using
converter.reverse().convert(b)
orconverter.reverse().convertAll(bs)
. - Use
converter
orconverter.reverse()
anywhere aFunction
is accepted (for exampleStream.map
). - Do not call
doForward(A)
ordoBackward(B)
directly; these exist only to be overridden.
Example
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));
- Since:
- 16.0
- Author:
- Mike Ward, Kurt Alfred Kluever, Gregory Kick
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
Converter()
Constructor for use by subclasses.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description <C> Converter<A,C>
andThen(Converter<B,C> secondConverter)
Returns a converter whoseconvert
method appliessecondConverter
to the result of this converter.B
apply(A a)
Deprecated.Provided to satisfy theFunction
interface; useconvert(A)
instead.B
convert(A a)
Returns a representation ofa
as an instance of typeB
.Iterable<B>
convertAll(Iterable<? extends A> fromIterable)
Returns an iterable that appliesconvert
to each element offromIterable
.protected abstract A
doBackward(B b)
Returns a representation ofb
as an instance of typeA
.protected abstract B
doForward(A a)
Returns a representation ofa
as an instance of typeB
.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 convertsthis.convert(a)
back to a value roughly equivalent toa
.
-
-
-
Constructor Detail
-
Converter
protected Converter()
Constructor for use by subclasses.
-
-
Method Detail
-
doForward
@ForOverride protected abstract B doForward(A a)
Returns a representation ofa
as an instance of typeB
. Ifa
cannot be converted, an unchecked exception (such asIllegalArgumentException
) should be thrown.- Parameters:
a
- the instance to convert; will never be null- Returns:
- the converted instance; must not be null
-
doBackward
@ForOverride protected abstract A doBackward(B b)
Returns a representation ofb
as an instance of typeA
. Ifb
cannot be converted, an unchecked exception (such asIllegalArgumentException
) should be thrown.- Parameters:
b
- the instance to convert; will never be null- Returns:
- the converted instance; must not be null
- Throws:
UnsupportedOperationException
- 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 aConverter<Chicken, ChickenNugget>
), then this is not logically aConverter
at all, and should just implementFunction
.
-
convert
@CanIgnoreReturnValue @CheckForNull public final B convert(@CheckForNull A a)
Returns a representation ofa
as an instance of typeB
.- Returns:
- the converted value; is null if and only if
a
is null
-
convertAll
@CanIgnoreReturnValue public Iterable<B> convertAll(Iterable<? extends A> fromIterable)
Returns an iterable that appliesconvert
to each element offromIterable
. The conversion is done lazily.The returned iterable's iterator supports
remove()
if the input iterator does. After a successfulremove()
call,fromIterable
no longer contains the corresponding element.
-
reverse
@CanIgnoreReturnValue public Converter<B,A> reverse()
Returns the reversed view of this converter, which convertsthis.convert(a)
back to a value roughly equivalent toa
.The returned converter is serializable if
this
converter is.Note: you should not override this method. It is non-final for legacy reasons.
-
andThen
public final <C> Converter<A,C> andThen(Converter<B,C> secondConverter)
Returns a converter whoseconvert
method appliessecondConverter
to the result of this converter. Itsreverse
method applies the converters in reverse order.The returned converter is serializable if
this
converter andsecondConverter
are.
-
apply
@Deprecated @CanIgnoreReturnValue @CheckForNull public final B apply(@CheckForNull A a)
Deprecated.Provided to satisfy theFunction
interface; useconvert(A)
instead.Description copied from interface:Function
Returns the result of applying this function toinput
. This method is generally expected, but not absolutely required, to have the following properties:- Its execution does not cause any observable side effects.
- The computation is consistent with equals; that is,
Objects.equal
(a, b)
implies thatObjects.equal(function.apply(a), function.apply(b))
.
-
equals
public boolean equals(@CheckForNull 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 returntrue
wheneverobject
is aConverter
that it considers interchangeable with this one. "Interchangeable" typically means thatObjects.equal(this.convert(a), that.convert(a))
is true for alla
of typeA
(and similarly forreverse
). Note that afalse
result from this method does not imply that the converters are known not to be interchangeable.
-
from
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 separate forward and backward functions. This is useful if the function instances already exist, or so that you can supply lambda expressions. If those circumstances don't apply, you probably don't need to use this; subclassConverter
and implement itsdoForward(A)
anddoBackward(B)
methods directly.These functions will never be passed
null
and must not under any circumstances returnnull
. 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.
- Since:
- 17.0
-
-