eaglercraft-1.8/sources/main/java/com/google/common/base/Converter.java

/*
 * Copyright (C) 2008 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.base;

import static com.google.common.base.Preconditions.checkNotNull;

import java.io.Serializable;
import java.util.Iterator;

import javax.annotation.Nullable;

import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;

/**
 * A function from {@code A} to {@code B} with an associated <i>reverse</i>
 * function from {@code B} to {@code A}; used for converting back and forth
 * between <i>different representations of the same information</i>.
 *
 * <h3>Invertibility</h3>
 *
 * <p>
 * The reverse operation <b>may</b> be a strict <i>inverse</i> (meaning that
 * {@code
 * converter.reverse().convert(converter.convert(a)).equals(a)} is always true).
 * However, it is very common (perhaps <i>more</i> common) for round-trip
 * conversion to be <i>lossy</i>. Consider an example round-trip using
 * {@link com.google.common.primitives.Doubles#stringConverter}:
 *
 * <ol>
 * <li>{@code stringConverter().convert("1.00")} returns the {@code Double}
 * value {@code 1.0}
 * <li>{@code stringConverter().reverse().convert(1.0)} returns the string
 * {@code "1.0"} -- <i>not</i> the same string ({@code "1.00"}) we started with
 * </ol>
 *
 * <p>
 * Note that it should still be the case that the round-tripped and original
 * objects are <i>similar</i>.
 *
 * <h3>Nullability</h3>
 *
 * <p>
 * A converter always converts {@code null} to {@code null} and non-null
 * references to non-null references. It would not make sense to consider
 * {@code null} and a non-null reference to be "different representations of the
 * same information", since one is distinguishable from <i>missing</i>
 * information and the other is not. The {@link #convert} method handles this
 * null behavior for all converters; implementations of {@link #doForward} and
 * {@link #doBackward} are guaranteed to never be passed {@code null}, and must
 * never return {@code null}.
 *
 * 
 * <h3>Common ways to use</h3>
 *
 * <p>
 * Getting a converter:
 *
 * <ul>
 * <li>Use a provided converter implementation, such as
 * {@link Enums#stringConverter},
 * {@link com.google.common.primitives.Ints#stringConverter
 * Ints.stringConverter} or the {@linkplain #reverse reverse} views of these.
 * <li>Convert between specific preset values using
 * {@link com.google.common.collect.Maps#asConverter Maps.asConverter}. For
 * example, use this to create a "fake" converter for a unit test. It is
 * unnecessary (and confusing) to <i>mock</i> the {@code Converter} type using a
 * mocking framework.
 * <li>Otherwise, extend this class and implement its {@link #doForward} and
 * {@link #doBackward} methods.
 * </ul>
 *
 * <p>
 * Using a converter:
 *
 * <ul>
 * <li>Convert one instance in the "forward" direction using
 * {@code converter.convert(a)}.
 * <li>Convert multiple instances "forward" using
 * {@code converter.convertAll(as)}.
 * <li>Convert in the "backward" direction using
 * {@code converter.reverse().convert(b)} or {@code
 *     converter.reverse().convertAll(bs)}.
 * <li>Use {@code converter} or {@code converter.reverse()} anywhere a
 * {@link Function} is accepted
 * <li><b>Do not</b> call {@link #doForward} or {@link #doBackward} directly;
 * these exist only to be overridden.
 * </ul>
 *
 * @author Mike Ward
 * @author Kurt Alfred Kluever
 * @author Gregory Kick
 * @since 16.0
 */
@Beta
@GwtCompatible
public abstract class Converter<A, B> implements Function<A, B> {
	private final boolean handleNullAutomatically;

	// We lazily cache the reverse view to avoid allocating on every call to
	// reverse().
	private transient Converter<B, A> reverse;

	/** Constructor for use by subclasses. */
	protected Converter() {
		this(true);
	}

	/**
	 * Constructor used only by {@code LegacyConverter} to suspend automatic
	 * null-handling.
	 */
	Converter(boolean handleNullAutomatically) {
		this.handleNullAutomatically = handleNullAutomatically;
	}

	// SPI methods (what subclasses must implement)

	/**
	 * Returns a representation of {@code a} as an instance of type {@code B}. If
	 * {@code a} cannot be converted, an unchecked exception (such as
	 * {@link IllegalArgumentException}) should be thrown.
	 *
	 * @param a the instance to convert; will never be null
	 * @return the converted instance; <b>must not</b> be null
	 */
	protected abstract B doForward(A a);

	/**
	 * Returns a representation of {@code b} as an instance of type {@code A}. If
	 * {@code b} cannot be converted, an unchecked exception (such as
	 * {@link IllegalArgumentException}) should be thrown.
	 *
	 * @param b the instance to convert; will never be null
	 * @return the converted instance; <b>must not</b> 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
	 *                                       unimplement<i>able</i> (for example,
	 *                                       consider a
	 *                                       {@code Converter<Chicken, ChickenNugget>}),
	 *                                       then this is not logically a
	 *                                       {@code Converter} at all, and should
	 *                                       just implement {@link Function}.
	 */
	protected abstract A doBackward(B b);

	// API (consumer-side) methods

	/**
	 * Returns a representation of {@code a} as an instance of type {@code B}.
	 *
	 * @return the converted value; is null <i>if and only if</i> {@code a} is null
	 */
	@Nullable
	public final B convert(@Nullable A a) {
		return correctedDoForward(a);
	}

	@Nullable
	B correctedDoForward(@Nullable A a) {
		if (handleNullAutomatically) {
			// TODO(kevinb): we shouldn't be checking for a null result at runtime. Assert?
			return a == null ? null : checkNotNull(doForward(a));
		} else {
			return doForward(a);
		}
	}

	@Nullable
	A correctedDoBackward(@Nullable B b) {
		if (handleNullAutomatically) {
			// TODO(kevinb): we shouldn't be checking for a null result at runtime. Assert?
			return b == null ? null : checkNotNull(doBackward(b));
		} else {
			return doBackward(b);
		}
	}

	/**
	 * Returns an iterable that applies {@code convert} to each element of
	 * {@code fromIterable}. The conversion is done lazily.
	 *
	 * <p>
	 * The returned iterable's iterator supports {@code remove()} if the input
	 * iterator does. After a successful {@code remove()} call, {@code fromIterable}
	 * no longer contains the corresponding element.
	 */
	public Iterable<B> convertAll(final Iterable<? extends A> fromIterable) {
		checkNotNull(fromIterable, "fromIterable");
		return new Iterable<B>() {
			@Override
			public Iterator<B> iterator() {
				return new Iterator<B>() {
					private final Iterator<? extends A> fromIterator = fromIterable.iterator();

					@Override
					public boolean hasNext() {
						return fromIterator.hasNext();
					}

					@Override
					public B next() {
						return convert(fromIterator.next());
					}

					@Override
					public void remove() {
						fromIterator.remove();
					}
				};
			}
		};
	}

	/**
	 * Returns the reversed view of this converter, which converts
	 * {@code this.convert(a)} back to a value roughly equivalent to {@code a}.
	 *
	 * <p>
	 * The returned converter is serializable if {@code this} converter is.
	 */
	// TODO(user): Make this method final
	public Converter<B, A> reverse() {
		Converter<B, A> result = reverse;
		return (result == null) ? reverse = new ReverseConverter<A, B>(this) : result;
	}

	private static final class ReverseConverter<A, B> extends Converter<B, A> implements Serializable {
		final Converter<A, B> original;

		ReverseConverter(Converter<A, B> original) {
			this.original = original;
		}

		/*
		 * These gymnastics are a little confusing. Basically this class has neither
		 * legacy nor non-legacy behavior; it just needs to let the behavior of the
		 * backing converter shine through. So, we override the correctedDo* methods,
		 * after which the do* methods should never be reached.
		 */

		@Override
		protected A doForward(B b) {
			throw new AssertionError();
		}

		@Override
		protected B doBackward(A a) {
			throw new AssertionError();
		}

		@Override
		@Nullable
		A correctedDoForward(@Nullable B b) {
			return original.correctedDoBackward(b);
		}

		@Override
		@Nullable
		B correctedDoBackward(@Nullable A a) {
			return original.correctedDoForward(a);
		}

		@Override
		public Converter<A, B> reverse() {
			return original;
		}

		@Override
		public boolean equals(@Nullable Object object) {
			if (object instanceof ReverseConverter) {
				ReverseConverter<?, ?> that = (ReverseConverter<?, ?>) object;
				return this.original.equals(that.original);
			}
			return false;
		}

		@Override
		public int hashCode() {
			return ~original.hashCode();
		}

		@Override
		public String toString() {
			return original + ".reverse()";
		}

		private static final long serialVersionUID = 0L;
	}

	/**
	 * Returns a converter whose {@code convert} method applies
	 * {@code secondConverter} to the result of this converter. Its {@code reverse}
	 * method applies the converters in reverse order.
	 *
	 * <p>
	 * The returned converter is serializable if {@code this} converter and
	 * {@code secondConverter} are.
	 */
	public <C> Converter<A, C> andThen(Converter<B, C> secondConverter) {
		return new ConverterComposition<A, B, C>(this, checkNotNull(secondConverter));
	}

	private static final class ConverterComposition<A, B, C> extends Converter<A, C> implements Serializable {
		final Converter<A, B> first;
		final Converter<B, C> second;

		ConverterComposition(Converter<A, B> first, Converter<B, C> second) {
			this.first = first;
			this.second = second;
		}

		/*
		 * These gymnastics are a little confusing. Basically this class has neither
		 * legacy nor non-legacy behavior; it just needs to let the behaviors of the
		 * backing converters shine through (which might even differ from each other!).
		 * So, we override the correctedDo* methods, after which the do* methods should
		 * never be reached.
		 */

		@Override
		protected C doForward(A a) {
			throw new AssertionError();
		}

		@Override
		protected A doBackward(C c) {
			throw new AssertionError();
		}

		@Override
		@Nullable
		C correctedDoForward(@Nullable A a) {
			return second.correctedDoForward(first.correctedDoForward(a));
		}

		@Override
		@Nullable
		A correctedDoBackward(@Nullable C c) {
			return first.correctedDoBackward(second.correctedDoBackward(c));
		}

		@Override
		public boolean equals(@Nullable Object object) {
			if (object instanceof ConverterComposition) {
				ConverterComposition<?, ?, ?> that = (ConverterComposition<?, ?, ?>) object;
				return this.first.equals(that.first) && this.second.equals(that.second);
			}
			return false;
		}

		@Override
		public int hashCode() {
			return 31 * first.hashCode() + second.hashCode();
		}

		@Override
		public String toString() {
			return first + ".andThen(" + second + ")";
		}

		private static final long serialVersionUID = 0L;
	}

	/**
	 * @deprecated Provided to satisfy the {@code Function} interface; use
	 *             {@link #convert} instead.
	 */
	@Deprecated
	@Override
	@Nullable
	public final B apply(@Nullable A a) {
		return convert(a);
	}

	/**
	 * Indicates whether another object is equal to this converter.
	 *
	 * <p>
	 * Most implementations will have no reason to override the behavior of
	 * {@link Object#equals}. However, an implementation may also choose to return
	 * {@code true} whenever {@code object} is a {@link Converter} that it considers
	 * <i>interchangeable</i> with this one. "Interchangeable" <i>typically</i>
	 * means that {@code Objects.equal(this.convert(a), that.convert(a))} is true
	 * for all {@code a} of type {@code A} (and similarly for {@code reverse}). Note
	 * that a {@code false} result from this method does not imply that the
	 * converters are known <i>not</i> to be interchangeable.
	 */
	@Override
	public boolean equals(@Nullable Object object) {
		return super.equals(object);
	}

	// Static converters

	/**
	 * Returns a converter based on <i>existing</i> forward and backward functions.
	 * Note that it is unnecessary to create <i>new</i> classes implementing
	 * {@code Function} just to pass them in here. Instead, simply subclass
	 * {@code Converter} and implement its {@link #doForward} and
	 * {@link #doBackward} methods directly.
	 *
	 * <p>
	 * These functions will never be passed {@code null} and must not under any
	 * circumstances return {@code null}. If a value cannot be converted, the
	 * function should throw an unchecked exception (typically, but not necessarily,
	 * {@link IllegalArgumentException}).
	 *
	 * <p>
	 * The returned converter is serializable if both provided functions are.
	 *
	 * @since 17.0
	 */
	public static <A, B> Converter<A, B> from(Function<? super A, ? extends B> forwardFunction,
			Function<? super B, ? extends A> backwardFunction) {
		return new FunctionBasedConverter<A, B>(forwardFunction, backwardFunction);
	}

	private static final class FunctionBasedConverter<A, B> extends Converter<A, B> implements Serializable {
		private final Function<? super A, ? extends B> forwardFunction;
		private final Function<? super B, ? extends A> backwardFunction;

		private FunctionBasedConverter(Function<? super A, ? extends B> forwardFunction,
				Function<? super B, ? extends A> backwardFunction) {
			this.forwardFunction = checkNotNull(forwardFunction);
			this.backwardFunction = checkNotNull(backwardFunction);
		}

		@Override
		protected B doForward(A a) {
			return forwardFunction.apply(a);
		}

		@Override
		protected A doBackward(B b) {
			return backwardFunction.apply(b);
		}

		@Override
		public boolean equals(@Nullable Object object) {
			if (object instanceof FunctionBasedConverter) {
				FunctionBasedConverter<?, ?> that = (FunctionBasedConverter<?, ?>) object;
				return this.forwardFunction.equals(that.forwardFunction)
						&& this.backwardFunction.equals(that.backwardFunction);
			}
			return false;
		}

		@Override
		public int hashCode() {
			return forwardFunction.hashCode() * 31 + backwardFunction.hashCode();
		}

		@Override
		public String toString() {
			return "Converter.from(" + forwardFunction + ", " + backwardFunction + ")";
		}
	}

	/**
	 * Returns a serializable converter that always converts or reverses an object
	 * to itself.
	 */
	@SuppressWarnings("unchecked") // implementation is "fully variant"
	public static <T> Converter<T, T> identity() {
		return (IdentityConverter<T>) IdentityConverter.INSTANCE;
	}

	/**
	 * A converter that always converts or reverses an object to itself. Note that T
	 * is now a "pass-through type".
	 */
	private static final class IdentityConverter<T> extends Converter<T, T> implements Serializable {
		static final IdentityConverter INSTANCE = new IdentityConverter();

		@Override
		protected T doForward(T t) {
			return t;
		}

		@Override
		protected T doBackward(T t) {
			return t;
		}

		@Override
		public IdentityConverter<T> reverse() {
			return this;
		}

		@Override
		public <S> Converter<T, S> andThen(Converter<T, S> otherConverter) {
			return checkNotNull(otherConverter, "otherConverter");
		}

		/*
		 * We *could* override convertAll() to return its input, but it's a rather
		 * pointless optimization and opened up a weird type-safety problem.
		 */

		@Override
		public String toString() {
			return "Converter.identity()";
		}

		private Object readResolve() {
			return INSTANCE;
		}

		private static final long serialVersionUID = 0L;
	}
}