Update #0 - First Release

sources/main/java/com/google/common/base/Absent.java

@@ -0,0 +1,106 @@
+/*
+ * Copyright (C) 2011 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.util.Collections;
+import java.util.Set;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Implementation of an {@link Optional} not containing a reference.
+ */
+@GwtCompatible
+final class Absent<T> extends Optional<T> {
+	static final Absent<Object> INSTANCE = new Absent<Object>();
+
+	@SuppressWarnings("unchecked") // implementation is "fully variant"
+	static <T> Optional<T> withType() {
+		return (Optional<T>) INSTANCE;
+	}
+
+	private Absent() {
+	}
+
+	@Override
+	public boolean isPresent() {
+		return false;
+	}
+
+	@Override
+	public T get() {
+		throw new IllegalStateException("Optional.get() cannot be called on an absent value");
+	}
+
+	@Override
+	public T or(T defaultValue) {
+		return checkNotNull(defaultValue, "use Optional.orNull() instead of Optional.or(null)");
+	}
+
+	@SuppressWarnings("unchecked") // safe covariant cast
+	@Override
+	public Optional<T> or(Optional<? extends T> secondChoice) {
+		return (Optional<T>) checkNotNull(secondChoice);
+	}
+
+	@Override
+	public T or(Supplier<? extends T> supplier) {
+		return checkNotNull(supplier.get(), "use Optional.orNull() instead of a Supplier that returns null");
+	}
+
+	@Override
+	@Nullable
+	public T orNull() {
+		return null;
+	}
+
+	@Override
+	public Set<T> asSet() {
+		return Collections.emptySet();
+	}
+
+	@Override
+	public <V> Optional<V> transform(Function<? super T, V> function) {
+		checkNotNull(function);
+		return Optional.absent();
+	}
+
+	@Override
+	public boolean equals(@Nullable Object object) {
+		return object == this;
+	}
+
+	@Override
+	public int hashCode() {
+		return 0x598df91c;
+	}
+
+	@Override
+	public String toString() {
+		return "Optional.absent()";
+	}
+
+	private Object readResolve() {
+		return INSTANCE;
+	}
+
+	private static final long serialVersionUID = 0;
+}

sources/main/java/com/google/common/base/AbstractIterator.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright (C) 2007 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.checkState;
+
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Note this class is a copy of
+ * {@link com.google.common.collect.AbstractIterator} (for dependency reasons).
+ */
+@GwtCompatible
+abstract class AbstractIterator<T> implements Iterator<T> {
+	private State state = State.NOT_READY;
+
+	protected AbstractIterator() {
+	}
+
+	private enum State {
+		READY, NOT_READY, DONE, FAILED,
+	}
+
+	private T next;
+
+	protected abstract T computeNext();
+
+	protected final T endOfData() {
+		state = State.DONE;
+		return null;
+	}
+
+	@Override
+	public final boolean hasNext() {
+		checkState(state != State.FAILED);
+		switch (state) {
+		case DONE:
+			return false;
+		case READY:
+			return true;
+		default:
+		}
+		return tryToComputeNext();
+	}
+
+	private boolean tryToComputeNext() {
+		state = State.FAILED; // temporary pessimism
+		next = computeNext();
+		if (state != State.DONE) {
+			state = State.READY;
+			return true;
+		}
+		return false;
+	}
+
+	@Override
+	public final T next() {
+		if (!hasNext()) {
+			throw new NoSuchElementException();
+		}
+		state = State.NOT_READY;
+		T result = next;
+		next = null;
+		return result;
+	}
+
+	@Override
+	public final void remove() {
+		throw new UnsupportedOperationException();
+	}
+}

sources/main/java/com/google/common/base/Ascii.java

@@ -0,0 +1,669 @@
+/*
+ * Copyright (C) 2010 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.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import javax.annotation.CheckReturnValue;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Static methods pertaining to ASCII characters (those in the range of values
+ * {@code 0x00} through {@code 0x7F}), and to strings containing such
+ * characters.
+ *
+ * <p>
+ * ASCII utilities also exist in other classes of this package:
+ * <ul>
+ * <!-- TODO(kevinb): how can we make this not produce a warning when building
+ * gwt javadoc? -->
+ * <li>{@link Charsets#US_ASCII} specifies the {@code Charset} of ASCII
+ * characters.
+ * <li>{@link CharMatcher#ASCII} matches ASCII characters and provides text
+ * processing methods which operate only on the ASCII characters of a string.
+ * </ul>
+ *
+ * @author Craig Berry
+ * @author Gregory Kick
+ * @since 7.0
+ */
+@GwtCompatible
+public final class Ascii {
+
+	private Ascii() {
+	}
+
+	/* The ASCII control characters, per RFC 20. */
+	/**
+	 * Null ('\0'): The all-zeros character which may serve to accomplish time fill
+	 * and media fill. Normally used as a C string terminator.
+	 * <p>
+	 * Although RFC 20 names this as "Null", note that it is distinct from the C/C++
+	 * "NULL" pointer.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte NUL = 0;
+
+	/**
+	 * Start of Heading: A communication control character used at the beginning of
+	 * a sequence of characters which constitute a machine-sensible address or
+	 * routing information. Such a sequence is referred to as the "heading." An STX
+	 * character has the effect of terminating a heading.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte SOH = 1;
+
+	/**
+	 * Start of Text: A communication control character which precedes a sequence of
+	 * characters that is to be treated as an entity and entirely transmitted
+	 * through to the ultimate destination. Such a sequence is referred to as
+	 * "text." STX may be used to terminate a sequence of characters started by SOH.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte STX = 2;
+
+	/**
+	 * End of Text: A communication control character used to terminate a sequence
+	 * of characters started with STX and transmitted as an entity.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte ETX = 3;
+
+	/**
+	 * End of Transmission: A communication control character used to indicate the
+	 * conclusion of a transmission, which may have contained one or more texts and
+	 * any associated headings.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte EOT = 4;
+
+	/**
+	 * Enquiry: A communication control character used in data communication systems
+	 * as a request for a response from a remote station. It may be used as a "Who
+	 * Are You" (WRU) to obtain identification, or may be used to obtain station
+	 * status, or both.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte ENQ = 5;
+
+	/**
+	 * Acknowledge: A communication control character transmitted by a receiver as
+	 * an affirmative response to a sender.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte ACK = 6;
+
+	/**
+	 * Bell ('\a'): A character for use when there is a need to call for human
+	 * attention. It may control alarm or attention devices.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte BEL = 7;
+
+	/**
+	 * Backspace ('\b'): A format effector which controls the movement of the
+	 * printing position one printing space backward on the same printing line.
+	 * (Applicable also to display devices.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte BS = 8;
+
+	/**
+	 * Horizontal Tabulation ('\t'): A format effector which controls the movement
+	 * of the printing position to the next in a series of predetermined positions
+	 * along the printing line. (Applicable also to display devices and the skip
+	 * function on punched cards.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte HT = 9;
+
+	/**
+	 * Line Feed ('\n'): A format effector which controls the movement of the
+	 * printing position to the next printing line. (Applicable also to display
+	 * devices.) Where appropriate, this character may have the meaning "New Line"
+	 * (NL), a format effector which controls the movement of the printing point to
+	 * the first printing position on the next printing line. Use of this convention
+	 * requires agreement between sender and recipient of data.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte LF = 10;
+
+	/**
+	 * Alternate name for {@link #LF}. ({@code LF} is preferred.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte NL = 10;
+
+	/**
+	 * Vertical Tabulation ('\v'): A format effector which controls the movement of
+	 * the printing position to the next in a series of predetermined printing
+	 * lines. (Applicable also to display devices.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte VT = 11;
+
+	/**
+	 * Form Feed ('\f'): A format effector which controls the movement of the
+	 * printing position to the first pre-determined printing line on the next form
+	 * or page. (Applicable also to display devices.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte FF = 12;
+
+	/**
+	 * Carriage Return ('\r'): A format effector which controls the movement of the
+	 * printing position to the first printing position on the same printing line.
+	 * (Applicable also to display devices.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte CR = 13;
+
+	/**
+	 * Shift Out: A control character indicating that the code combinations which
+	 * follow shall be interpreted as outside of the character set of the standard
+	 * code table until a Shift In character is reached.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte SO = 14;
+
+	/**
+	 * Shift In: A control character indicating that the code combinations which
+	 * follow shall be interpreted according to the standard code table.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte SI = 15;
+
+	/**
+	 * Data Link Escape: A communication control character which will change the
+	 * meaning of a limited number of contiguously following characters. It is used
+	 * exclusively to provide supplementary controls in data communication networks.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte DLE = 16;
+
+	/**
+	 * Device Control 1. Characters for the control of ancillary devices associated
+	 * with data processing or telecommunication systems, more especially switching
+	 * devices "on" or "off." (If a single "stop" control is required to interrupt
+	 * or turn off ancillary devices, DC4 is the preferred assignment.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte DC1 = 17; // aka XON
+
+	/**
+	 * Transmission On: Although originally defined as DC1, this ASCII control
+	 * character is now better known as the XON code used for software flow control
+	 * in serial communications. The main use is restarting the transmission after
+	 * the communication has been stopped by the XOFF control code.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte XON = 17; // aka DC1
+
+	/**
+	 * Device Control 2. Characters for the control of ancillary devices associated
+	 * with data processing or telecommunication systems, more especially switching
+	 * devices "on" or "off." (If a single "stop" control is required to interrupt
+	 * or turn off ancillary devices, DC4 is the preferred assignment.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte DC2 = 18;
+
+	/**
+	 * Device Control 3. Characters for the control of ancillary devices associated
+	 * with data processing or telecommunication systems, more especially switching
+	 * devices "on" or "off." (If a single "stop" control is required to interrupt
+	 * or turn off ancillary devices, DC4 is the preferred assignment.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte DC3 = 19; // aka XOFF
+
+	/**
+	 * Transmission off. See {@link #XON} for explanation.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte XOFF = 19; // aka DC3
+
+	/**
+	 * Device Control 4. Characters for the control of ancillary devices associated
+	 * with data processing or telecommunication systems, more especially switching
+	 * devices "on" or "off." (If a single "stop" control is required to interrupt
+	 * or turn off ancillary devices, DC4 is the preferred assignment.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte DC4 = 20;
+
+	/**
+	 * Negative Acknowledge: A communication control character transmitted by a
+	 * receiver as a negative response to the sender.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte NAK = 21;
+
+	/**
+	 * Synchronous Idle: A communication control character used by a synchronous
+	 * transmission system in the absence of any other character to provide a signal
+	 * from which synchronism may be achieved or retained.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte SYN = 22;
+
+	/**
+	 * End of Transmission Block: A communication control character used to indicate
+	 * the end of a block of data for communication purposes. ETB is used for
+	 * blocking data where the block structure is not necessarily related to the
+	 * processing format.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte ETB = 23;
+
+	/**
+	 * Cancel: A control character used to indicate that the data with which it is
+	 * sent is in error or is to be disregarded.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte CAN = 24;
+
+	/**
+	 * End of Medium: A control character associated with the sent data which may be
+	 * used to identify the physical end of the medium, or the end of the used, or
+	 * wanted, portion of information recorded on a medium. (The position of this
+	 * character does not necessarily correspond to the physical end of the medium.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte EM = 25;
+
+	/**
+	 * Substitute: A character that may be substituted for a character which is
+	 * determined to be invalid or in error.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte SUB = 26;
+
+	/**
+	 * Escape: A control character intended to provide code extension (supplementary
+	 * characters) in general information interchange. The Escape character itself
+	 * is a prefix affecting the interpretation of a limited number of contiguously
+	 * following characters.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte ESC = 27;
+
+	/**
+	 * File Separator: These four information separators may be used within data in
+	 * optional fashion, except that their hierarchical relationship shall be: FS is
+	 * the most inclusive, then GS, then RS, and US is least inclusive. (The content
+	 * and length of a File, Group, Record, or Unit are not specified.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte FS = 28;
+
+	/**
+	 * Group Separator: These four information separators may be used within data in
+	 * optional fashion, except that their hierarchical relationship shall be: FS is
+	 * the most inclusive, then GS, then RS, and US is least inclusive. (The content
+	 * and length of a File, Group, Record, or Unit are not specified.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte GS = 29;
+
+	/**
+	 * Record Separator: These four information separators may be used within data
+	 * in optional fashion, except that their hierarchical relationship shall be: FS
+	 * is the most inclusive, then GS, then RS, and US is least inclusive. (The
+	 * content and length of a File, Group, Record, or Unit are not specified.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte RS = 30;
+
+	/**
+	 * Unit Separator: These four information separators may be used within data in
+	 * optional fashion, except that their hierarchical relationship shall be: FS is
+	 * the most inclusive, then GS, then RS, and US is least inclusive. (The content
+	 * and length of a File, Group, Record, or Unit are not specified.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte US = 31;
+
+	/**
+	 * Space: A normally non-printing graphic character used to separate words. It
+	 * is also a format effector which controls the movement of the printing
+	 * position, one printing position forward. (Applicable also to display
+	 * devices.)
+	 *
+	 * @since 8.0
+	 */
+	public static final byte SP = 32;
+
+	/**
+	 * Alternate name for {@link #SP}.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte SPACE = 32;
+
+	/**
+	 * Delete: This character is used primarily to "erase" or "obliterate" erroneous
+	 * or unwanted characters in perforated tape.
+	 *
+	 * @since 8.0
+	 */
+	public static final byte DEL = 127;
+
+	/**
+	 * The minimum value of an ASCII character.
+	 *
+	 * @since 9.0 (was type {@code int} before 12.0)
+	 */
+	public static final char MIN = 0;
+
+	/**
+	 * The maximum value of an ASCII character.
+	 *
+	 * @since 9.0 (was type {@code int} before 12.0)
+	 */
+	public static final char MAX = 127;
+
+	/**
+	 * Returns a copy of the input string in which all
+	 * {@linkplain #isUpperCase(char) uppercase ASCII characters} have been
+	 * converted to lowercase. All other characters are copied without modification.
+	 */
+	public static String toLowerCase(String string) {
+		int length = string.length();
+		for (int i = 0; i < length; i++) {
+			if (isUpperCase(string.charAt(i))) {
+				char[] chars = string.toCharArray();
+				for (; i < length; i++) {
+					char c = chars[i];
+					if (isUpperCase(c)) {
+						chars[i] = (char) (c ^ 0x20);
+					}
+				}
+				return String.valueOf(chars);
+			}
+		}
+		return string;
+	}
+
+	/**
+	 * Returns a copy of the input character sequence in which all
+	 * {@linkplain #isUpperCase(char) uppercase ASCII characters} have been
+	 * converted to lowercase. All other characters are copied without modification.
+	 *
+	 * @since 14.0
+	 */
+	public static String toLowerCase(CharSequence chars) {
+		if (chars instanceof String) {
+			return toLowerCase((String) chars);
+		}
+		int length = chars.length();
+		StringBuilder builder = new StringBuilder(length);
+		for (int i = 0; i < length; i++) {
+			builder.append(toLowerCase(chars.charAt(i)));
+		}
+		return builder.toString();
+	}
+
+	/**
+	 * If the argument is an {@linkplain #isUpperCase(char) uppercase ASCII
+	 * character} returns the lowercase equivalent. Otherwise returns the argument.
+	 */
+	public static char toLowerCase(char c) {
+		return isUpperCase(c) ? (char) (c ^ 0x20) : c;
+	}
+
+	/**
+	 * Returns a copy of the input string in which all
+	 * {@linkplain #isLowerCase(char) lowercase ASCII characters} have been
+	 * converted to uppercase. All other characters are copied without modification.
+	 */
+	public static String toUpperCase(String string) {
+		int length = string.length();
+		for (int i = 0; i < length; i++) {
+			if (isLowerCase(string.charAt(i))) {
+				char[] chars = string.toCharArray();
+				for (; i < length; i++) {
+					char c = chars[i];
+					if (isLowerCase(c)) {
+						chars[i] = (char) (c & 0x5f);
+					}
+				}
+				return String.valueOf(chars);
+			}
+		}
+		return string;
+	}
+
+	/**
+	 * Returns a copy of the input character sequence in which all
+	 * {@linkplain #isLowerCase(char) lowercase ASCII characters} have been
+	 * converted to uppercase. All other characters are copied without modification.
+	 *
+	 * @since 14.0
+	 */
+	public static String toUpperCase(CharSequence chars) {
+		if (chars instanceof String) {
+			return toUpperCase((String) chars);
+		}
+		int length = chars.length();
+		StringBuilder builder = new StringBuilder(length);
+		for (int i = 0; i < length; i++) {
+			builder.append(toUpperCase(chars.charAt(i)));
+		}
+		return builder.toString();
+	}
+
+	/**
+	 * If the argument is a {@linkplain #isLowerCase(char) lowercase ASCII
+	 * character} returns the uppercase equivalent. Otherwise returns the argument.
+	 */
+	public static char toUpperCase(char c) {
+		return isLowerCase(c) ? (char) (c & 0x5f) : c;
+	}
+
+	/**
+	 * Indicates whether {@code c} is one of the twenty-six lowercase ASCII
+	 * alphabetic characters between {@code 'a'} and {@code 'z'} inclusive. All
+	 * others (including non-ASCII characters) return {@code false}.
+	 */
+	public static boolean isLowerCase(char c) {
+		// Note: This was benchmarked against the alternate expression "(char)(c - 'a')
+		// < 26" (Nov '13)
+		// and found to perform at least as well, or better.
+		return (c >= 'a') && (c <= 'z');
+	}
+
+	/**
+	 * Indicates whether {@code c} is one of the twenty-six uppercase ASCII
+	 * alphabetic characters between {@code 'A'} and {@code 'Z'} inclusive. All
+	 * others (including non-ASCII characters) return {@code false}.
+	 */
+	public static boolean isUpperCase(char c) {
+		return (c >= 'A') && (c <= 'Z');
+	}
+
+	/**
+	 * Truncates the given character sequence to the given maximum length. If the
+	 * length of the sequence is greater than {@code maxLength}, the returned string
+	 * will be exactly {@code maxLength} chars in length and will end with the given
+	 * {@code truncationIndicator}. Otherwise, the sequence will be returned as a
+	 * string with no changes to the content.
+	 *
+	 * <p>
+	 * Examples:
+	 *
+	 * <pre>
+	 *    {@code
+	 *   Ascii.truncate("foobar", 7, "..."); // returns "foobar"
+	 *   Ascii.truncate("foobar", 5, "..."); // returns "fo..." }
+	 * </pre>
+	 *
+	 * <p>
+	 * <b>Note:</b> This method <i>may</i> work with certain non-ASCII text but is
+	 * not safe for use with arbitrary Unicode text. It is mostly intended for use
+	 * with text that is known to be safe for use with it (such as all-ASCII text)
+	 * and for simple debugging text. When using this method, consider the
+	 * following:
+	 *
+	 * <ul>
+	 * <li>it may split surrogate pairs</li>
+	 * <li>it may split characters and combining characters</li>
+	 * <li>it does not consider word boundaries</li>
+	 * <li>if truncating for display to users, there are other considerations that
+	 * must be taken into account</li>
+	 * <li>the appropriate truncation indicator may be locale-dependent</li>
+	 * <li>it is safe to use non-ASCII characters in the truncation indicator</li>
+	 * </ul>
+	 *
+	 *
+	 * @throws IllegalArgumentException if {@code maxLength} is less than the length
+	 *                                  of {@code truncationIndicator}
+	 * @since 16.0
+	 */
+	@Beta
+	@CheckReturnValue
+	public static String truncate(CharSequence seq, int maxLength, String truncationIndicator) {
+		checkNotNull(seq);
+
+		// length to truncate the sequence to, not including the truncation indicator
+		int truncationLength = maxLength - truncationIndicator.length();
+
+		// in this worst case, this allows a maxLength equal to the length of the
+		// truncationIndicator,
+		// meaning that a string will be truncated to just the truncation indicator
+		// itself
+		checkArgument(truncationLength >= 0, "maxLength (%s) must be >= length of the truncation indicator (%s)",
+				maxLength, truncationIndicator.length());
+
+		if (seq.length() <= maxLength) {
+			String string = seq.toString();
+			if (string.length() <= maxLength) {
+				return string;
+			}
+			// if the length of the toString() result was > maxLength for some reason,
+			// truncate that
+			seq = string;
+		}
+
+		return new StringBuilder(maxLength).append(seq, 0, truncationLength).append(truncationIndicator).toString();
+	}
+
+	/**
+	 * Indicates whether the contents of the given character sequences {@code s1}
+	 * and {@code s2} are equal, ignoring the case of any ASCII alphabetic
+	 * characters between {@code 'a'} and {@code 'z'} or {@code 'A'} and {@code 'Z'}
+	 * inclusive.
+	 *
+	 * <p>
+	 * This method is significantly faster than {@link String#equalsIgnoreCase} and
+	 * should be used in preference if at least one of the parameters is known to
+	 * contain only ASCII characters.
+	 *
+	 * <p>
+	 * Note however that this method does not always behave identically to
+	 * expressions such as:
+	 * <ul>
+	 * <li>{@code string.toUpperCase().equals("UPPER CASE ASCII")}
+	 * <li>{@code string.toLowerCase().equals("lower case ascii")}
+	 * </ul>
+	 * <p>
+	 * due to case-folding of some non-ASCII characters (which does not occur in
+	 * {@link String#equalsIgnoreCase}). However in almost all cases that ASCII
+	 * strings are used, the author probably wanted the behavior provided by this
+	 * method rather than the subtle and sometimes surprising behavior of
+	 * {@code toUpperCase()} and {@code toLowerCase()}.
+	 *
+	 * @since 16.0
+	 */
+	@Beta
+	public static boolean equalsIgnoreCase(CharSequence s1, CharSequence s2) {
+		// Calling length() is the null pointer check (so do it before we can exit
+		// early).
+		int length = s1.length();
+		if (s1 == s2) {
+			return true;
+		}
+		if (length != s2.length()) {
+			return false;
+		}
+		for (int i = 0; i < length; i++) {
+			char c1 = s1.charAt(i);
+			char c2 = s2.charAt(i);
+			if (c1 == c2) {
+				continue;
+			}
+			int alphaIndex = getAlphaIndex(c1);
+			// This was also benchmarked using '&' to avoid branching (but always evaluate
+			// the rhs),
+			// however this showed no obvious improvement.
+			if (alphaIndex < 26 && alphaIndex == getAlphaIndex(c2)) {
+				continue;
+			}
+			return false;
+		}
+		return true;
+	}
+
+	/**
+	 * Returns the non-negative index value of the alpha character {@code c},
+	 * regardless of case. Ie, 'a'/'A' returns 0 and 'z'/'Z' returns 25. Non-alpha
+	 * characters return a value of 26 or greater.
+	 */
+	private static int getAlphaIndex(char c) {
+		// Fold upper-case ASCII to lower-case and make zero-indexed and unsigned (by
+		// casting to char).
+		return (char) ((c | 0x20) - 'a');
+	}
+}

sources/main/java/com/google/common/base/CaseFormat.java

@@ -0,0 +1,228 @@
+/*
+ * Copyright (C) 2006 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 javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Utility class for converting between various ASCII case formats. Behavior is
+ * undefined for non-ASCII input.
+ *
+ * @author Mike Bostock
+ * @since 1.0
+ */
+@GwtCompatible
+public enum CaseFormat {
+	/**
+	 * Hyphenated variable naming convention, e.g., "lower-hyphen".
+	 */
+	LOWER_HYPHEN(CharMatcher.is('-'), "-") {
+		@Override
+		String normalizeWord(String word) {
+			return Ascii.toLowerCase(word);
+		}
+
+		@Override
+		String convert(CaseFormat format, String s) {
+			if (format == LOWER_UNDERSCORE) {
+				return s.replace('-', '_');
+			}
+			if (format == UPPER_UNDERSCORE) {
+				return Ascii.toUpperCase(s.replace('-', '_'));
+			}
+			return super.convert(format, s);
+		}
+	},
+
+	/**
+	 * C++ variable naming convention, e.g., "lower_underscore".
+	 */
+	LOWER_UNDERSCORE(CharMatcher.is('_'), "_") {
+		@Override
+		String normalizeWord(String word) {
+			return Ascii.toLowerCase(word);
+		}
+
+		@Override
+		String convert(CaseFormat format, String s) {
+			if (format == LOWER_HYPHEN) {
+				return s.replace('_', '-');
+			}
+			if (format == UPPER_UNDERSCORE) {
+				return Ascii.toUpperCase(s);
+			}
+			return super.convert(format, s);
+		}
+	},
+
+	/**
+	 * Java variable naming convention, e.g., "lowerCamel".
+	 */
+	LOWER_CAMEL(CharMatcher.inRange('A', 'Z'), "") {
+		@Override
+		String normalizeWord(String word) {
+			return firstCharOnlyToUpper(word);
+		}
+	},
+
+	/**
+	 * Java and C++ class naming convention, e.g., "UpperCamel".
+	 */
+	UPPER_CAMEL(CharMatcher.inRange('A', 'Z'), "") {
+		@Override
+		String normalizeWord(String word) {
+			return firstCharOnlyToUpper(word);
+		}
+	},
+
+	/**
+	 * Java and C++ constant naming convention, e.g., "UPPER_UNDERSCORE".
+	 */
+	UPPER_UNDERSCORE(CharMatcher.is('_'), "_") {
+		@Override
+		String normalizeWord(String word) {
+			return Ascii.toUpperCase(word);
+		}
+
+		@Override
+		String convert(CaseFormat format, String s) {
+			if (format == LOWER_HYPHEN) {
+				return Ascii.toLowerCase(s.replace('_', '-'));
+			}
+			if (format == LOWER_UNDERSCORE) {
+				return Ascii.toLowerCase(s);
+			}
+			return super.convert(format, s);
+		}
+	};
+
+	private final CharMatcher wordBoundary;
+	private final String wordSeparator;
+
+	CaseFormat(CharMatcher wordBoundary, String wordSeparator) {
+		this.wordBoundary = wordBoundary;
+		this.wordSeparator = wordSeparator;
+	}
+
+	/**
+	 * Converts the specified {@code String str} from this format to the specified
+	 * {@code format}. A "best effort" approach is taken; if {@code str} does not
+	 * conform to the assumed format, then the behavior of this method is undefined
+	 * but we make a reasonable effort at converting anyway.
+	 */
+	public final String to(CaseFormat format, String str) {
+		checkNotNull(format);
+		checkNotNull(str);
+		return (format == this) ? str : convert(format, str);
+	}
+
+	/**
+	 * Enum values can override for performance reasons.
+	 */
+	String convert(CaseFormat format, String s) {
+		// deal with camel conversion
+		StringBuilder out = null;
+		int i = 0;
+		int j = -1;
+		while ((j = wordBoundary.indexIn(s, ++j)) != -1) {
+			if (i == 0) {
+				// include some extra space for separators
+				out = new StringBuilder(s.length() + 4 * wordSeparator.length());
+				out.append(format.normalizeFirstWord(s.substring(i, j)));
+			} else {
+				out.append(format.normalizeWord(s.substring(i, j)));
+			}
+			out.append(format.wordSeparator);
+			i = j + wordSeparator.length();
+		}
+		return (i == 0) ? format.normalizeFirstWord(s) : out.append(format.normalizeWord(s.substring(i))).toString();
+	}
+
+	/**
+	 * Returns a {@code Converter} that converts strings from this format to
+	 * {@code targetFormat}.
+	 *
+	 * @since 16.0
+	 */
+	@Beta
+	public Converter<String, String> converterTo(CaseFormat targetFormat) {
+		return new StringConverter(this, targetFormat);
+	}
+
+	private static final class StringConverter extends Converter<String, String> implements Serializable {
+
+		private final CaseFormat sourceFormat;
+		private final CaseFormat targetFormat;
+
+		StringConverter(CaseFormat sourceFormat, CaseFormat targetFormat) {
+			this.sourceFormat = checkNotNull(sourceFormat);
+			this.targetFormat = checkNotNull(targetFormat);
+		}
+
+		@Override
+		protected String doForward(String s) {
+			// TODO(kevinb): remove null boilerplate (convert() will do it automatically)
+			return s == null ? null : sourceFormat.to(targetFormat, s);
+		}
+
+		@Override
+		protected String doBackward(String s) {
+			// TODO(kevinb): remove null boilerplate (convert() will do it automatically)
+			return s == null ? null : targetFormat.to(sourceFormat, s);
+		}
+
+		@Override
+		public boolean equals(@Nullable Object object) {
+			if (object instanceof StringConverter) {
+				StringConverter that = (StringConverter) object;
+				return sourceFormat.equals(that.sourceFormat) && targetFormat.equals(that.targetFormat);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return sourceFormat.hashCode() ^ targetFormat.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return sourceFormat + ".converterTo(" + targetFormat + ")";
+		}
+
+		private static final long serialVersionUID = 0L;
+	}
+
+	abstract String normalizeWord(String word);
+
+	private String normalizeFirstWord(String word) {
+		return (this == LOWER_CAMEL) ? Ascii.toLowerCase(word) : normalizeWord(word);
+	}
+
+	private static String firstCharOnlyToUpper(String word) {
+		return (word.isEmpty()) ? word
+				: new StringBuilder(word.length()).append(Ascii.toUpperCase(word.charAt(0)))
+						.append(Ascii.toLowerCase(word.substring(1))).toString();
+	}
+}

sources/main/java/com/google/common/base/Charsets.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright (C) 2007 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 java.nio.charset.Charset;
+
+import com.google.common.annotations.GwtCompatible;
+import com.google.common.annotations.GwtIncompatible;
+
+/**
+ * Contains constant definitions for the six standard {@link Charset} instances,
+ * which are guaranteed to be supported by all Java platform implementations.
+ *
+ * <p>
+ * Assuming you're free to choose, note that <b>{@link #UTF_8} is widely
+ * preferred</b>.
+ *
+ * <p>
+ * See the Guava User Guide article on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/StringsExplained#Charsets">
+ * {@code Charsets}</a>.
+ *
+ * @author Mike Bostock
+ * @since 1.0
+ */
+@GwtCompatible(emulated = true)
+public final class Charsets {
+	private Charsets() {
+	}
+
+	/**
+	 * UTF-8: eight-bit UCS Transformation Format.
+	 *
+	 */
+	public static final Charset UTF_8 = Charset.forName("UTF-8");
+
+	/*
+	 * Please do not add new Charset references to this class, unless those
+	 * character encodings are part of the set required to be supported by all Java
+	 * platform implementations! Any Charsets initialized here may cause unexpected
+	 * delays when this class is loaded. See the Charset Javadocs for the list of
+	 * built-in character encodings.
+	 */
+}

sources/main/java/com/google/common/base/Converter.java

@@ -0,0 +1,528 @@
+/*
+ * 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;
+	}
+}

sources/main/java/com/google/common/base/Defaults.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright (C) 2007 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.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * This class provides default values for all Java types, as defined by the JLS.
+ *
+ * @author Ben Yu
+ * @since 1.0
+ */
+public final class Defaults {
+	private Defaults() {
+	}
+
+	private static final Map<Class<?>, Object> DEFAULTS;
+
+	static {
+		// Only add to this map via put(Map, Class<T>, T)
+		Map<Class<?>, Object> map = new HashMap<Class<?>, Object>();
+		put(map, boolean.class, false);
+		put(map, char.class, '\0');
+		put(map, byte.class, (byte) 0);
+		put(map, short.class, (short) 0);
+		put(map, int.class, 0);
+		put(map, long.class, 0L);
+		put(map, float.class, 0f);
+		put(map, double.class, 0d);
+		DEFAULTS = Collections.unmodifiableMap(map);
+	}
+
+	private static <T> void put(Map<Class<?>, Object> map, Class<T> type, T value) {
+		map.put(type, value);
+	}
+
+	/**
+	 * Returns the default value of {@code type} as defined by JLS --- {@code 0} for
+	 * numbers, {@code
+	 * false} for {@code boolean} and {@code '\0'} for {@code char}. For
+	 * non-primitive types and {@code void}, null is returned.
+	 */
+	public static <T> T defaultValue(Class<T> type) {
+		// Primitives.wrap(type).cast(...) would avoid the warning, but we can't use
+		// that from here
+		@SuppressWarnings("unchecked") // the put method enforces this key-value relationship
+		T t = (T) DEFAULTS.get(checkNotNull(type));
+		return t;
+	}
+}

sources/main/java/com/google/common/base/Enums.java

@@ -0,0 +1,197 @@
+/*
+ * Copyright (C) 2011 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.lang.ref.WeakReference;
+import java.util.EnumSet;
+import java.util.HashMap;
+import java.util.Map;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+import com.google.common.annotations.GwtIncompatible;
+
+/**
+ * Utility methods for working with {@link Enum} instances.
+ *
+ * @author Steve McKay
+ *
+ * @since 9.0
+ */
+@GwtCompatible(emulated = true)
+@Beta
+public final class Enums {
+
+	private Enums() {
+	}
+
+	/**
+	 * Returns a {@link Function} that maps an {@link Enum} name to the associated
+	 * {@code Enum} constant. The {@code Function} will return {@code null} if the
+	 * {@code Enum} constant does not exist.
+	 *
+	 * @param enumClass the {@link Class} of the {@code Enum} declaring the constant
+	 *                  values
+	 * @deprecated Use {@link Enums#stringConverter} instead. Note that the string
+	 *             converter has slightly different behavior: it throws
+	 *             {@link IllegalArgumentException} if the enum constant does not
+	 *             exist rather than returning {@code null}. It also converts
+	 *             {@code null} to {@code null} rather than throwing
+	 *             {@link NullPointerException}. This method is scheduled for
+	 *             removal in Guava 18.0.
+	 */
+	@Deprecated
+	public static <T extends Enum<T>> Function<String, T> valueOfFunction(Class<T> enumClass) {
+		return new ValueOfFunction<T>(enumClass);
+	}
+
+	/**
+	 * A {@link Function} that maps an {@link Enum} name to the associated constant,
+	 * or {@code null} if the constant does not exist.
+	 */
+	private static final class ValueOfFunction<T extends Enum<T>> implements Function<String, T>, Serializable {
+
+		private final Class<T> enumClass;
+
+		private ValueOfFunction(Class<T> enumClass) {
+			this.enumClass = checkNotNull(enumClass);
+		}
+
+		@Override
+		public T apply(String value) {
+			try {
+				return Enum.valueOf(enumClass, value);
+			} catch (IllegalArgumentException e) {
+				return null;
+			}
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			return obj instanceof ValueOfFunction && enumClass.equals(((ValueOfFunction) obj).enumClass);
+		}
+
+		@Override
+		public int hashCode() {
+			return enumClass.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return "Enums.valueOf(" + enumClass + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns an optional enum constant for the given type, using
+	 * {@link Enum#valueOf}. If the constant does not exist, {@link Optional#absent}
+	 * is returned. A common use case is for parsing user input or falling back to a
+	 * default enum constant. For example,
+	 * {@code Enums.getIfPresent(Country.class, countryInput).or(Country.DEFAULT);}
+	 *
+	 * @since 12.0
+	 */
+	public static <T extends Enum<T>> Optional<T> getIfPresent(Class<T> enumClass, String value) {
+		checkNotNull(enumClass);
+		checkNotNull(value);
+		return Platform.getEnumIfPresent(enumClass, value);
+	}
+
+	@GwtIncompatible("java.lang.ref.WeakReference")
+	private static final Map<Class<? extends Enum<?>>, Map<String, WeakReference<? extends Enum<?>>>> enumConstantCache = new HashMap<Class<? extends Enum<?>>, Map<String, WeakReference<? extends Enum<?>>>>();
+
+	@GwtIncompatible("java.lang.ref.WeakReference")
+	private static <T extends Enum<T>> Map<String, WeakReference<? extends Enum<?>>> populateCache(Class<T> enumClass) {
+		Map<String, WeakReference<? extends Enum<?>>> result = new HashMap<String, WeakReference<? extends Enum<?>>>();
+		for (T enumInstance : EnumSet.allOf(enumClass)) {
+			result.put(enumInstance.name(), new WeakReference<Enum<?>>(enumInstance));
+		}
+		enumConstantCache.put(enumClass, result);
+		return result;
+	}
+
+	@GwtIncompatible("java.lang.ref.WeakReference")
+	static <T extends Enum<T>> Map<String, WeakReference<? extends Enum<?>>> getEnumConstants(Class<T> enumClass) {
+		synchronized (enumConstantCache) {
+			Map<String, WeakReference<? extends Enum<?>>> constants = enumConstantCache.get(enumClass);
+			if (constants == null) {
+				constants = populateCache(enumClass);
+			}
+			return constants;
+		}
+	}
+
+	/**
+	 * Returns a converter that converts between strings and {@code enum} values of
+	 * type {@code enumClass} using {@link Enum#valueOf(Class, String)} and
+	 * {@link Enum#name()}. The converter will throw an
+	 * {@code IllegalArgumentException} if the argument is not the name of any enum
+	 * constant in the specified enum.
+	 *
+	 * @since 16.0
+	 */
+	public static <T extends Enum<T>> Converter<String, T> stringConverter(final Class<T> enumClass) {
+		return new StringConverter<T>(enumClass);
+	}
+
+	private static final class StringConverter<T extends Enum<T>> extends Converter<String, T> implements Serializable {
+
+		private final Class<T> enumClass;
+
+		StringConverter(Class<T> enumClass) {
+			this.enumClass = checkNotNull(enumClass);
+		}
+
+		@Override
+		protected T doForward(String value) {
+			return Enum.valueOf(enumClass, value);
+		}
+
+		@Override
+		protected String doBackward(T enumValue) {
+			return enumValue.name();
+		}
+
+		@Override
+		public boolean equals(@Nullable Object object) {
+			if (object instanceof StringConverter) {
+				StringConverter<?> that = (StringConverter<?>) object;
+				return this.enumClass.equals(that.enumClass);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return enumClass.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return "Enums.stringConverter(" + enumClass.getName() + ".class)";
+		}
+
+		private static final long serialVersionUID = 0L;
+	}
+}

sources/main/java/com/google/common/base/Equivalence.java

@@ -0,0 +1,409 @@
+/*
+ * Copyright (C) 2010 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 javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * A strategy for determining whether two instances are considered equivalent.
+ * Examples of equivalences are the {@linkplain #identity() identity
+ * equivalence} and {@linkplain #equals equals equivalence}.
+ *
+ * @author Bob Lee
+ * @author Ben Yu
+ * @author Gregory Kick
+ * @since 10.0
+ *        (<a href="http://code.google.com/p/guava-libraries/wiki/Compatibility"
+ *        >mostly source-compatible</a> since 4.0)
+ */
+@GwtCompatible
+public abstract class Equivalence<T> {
+	/**
+	 * Constructor for use by subclasses.
+	 */
+	protected Equivalence() {
+	}
+
+	/**
+	 * Returns {@code true} if the given objects are considered equivalent.
+	 *
+	 * <p>
+	 * The {@code equivalent} method implements an equivalence relation on object
+	 * references:
+	 *
+	 * <ul>
+	 * <li>It is <i>reflexive</i>: for any reference {@code x}, including null,
+	 * {@code
+	 *     equivalent(x, x)} returns {@code true}.
+	 * <li>It is <i>symmetric</i>: for any references {@code x} and {@code y},
+	 * {@code
+	 *     equivalent(x, y) == equivalent(y, x)}.
+	 * <li>It is <i>transitive</i>: for any references {@code x}, {@code y}, and
+	 * {@code z}, if {@code equivalent(x, y)} returns {@code true} and
+	 * {@code equivalent(y, z)} returns {@code
+	 *     true}, then {@code equivalent(x, z)} returns {@code true}.
+	 * <li>It is <i>consistent</i>: for any references {@code x} and {@code y},
+	 * multiple invocations of {@code equivalent(x, y)} consistently return
+	 * {@code true} or consistently return {@code
+	 *     false} (provided that neither {@code x} nor {@code y} is modified).
+	 * </ul>
+	 */
+	public final boolean equivalent(@Nullable T a, @Nullable T b) {
+		if (a == b) {
+			return true;
+		}
+		if (a == null || b == null) {
+			return false;
+		}
+		return doEquivalent(a, b);
+	}
+
+	/**
+	 * Returns {@code true} if {@code a} and {@code b} are considered equivalent.
+	 *
+	 * <p>
+	 * Called by {@link #equivalent}. {@code a} and {@code b} are not the same
+	 * object and are not nulls.
+	 *
+	 * @since 10.0 (previously, subclasses would override equivalent())
+	 */
+	protected abstract boolean doEquivalent(T a, T b);
+
+	/**
+	 * Returns a hash code for {@code t}.
+	 *
+	 * <p>
+	 * The {@code hash} has the following properties:
+	 * <ul>
+	 * <li>It is <i>consistent</i>: for any reference {@code x}, multiple
+	 * invocations of {@code hash(x}} consistently return the same value provided
+	 * {@code x} remains unchanged according to the definition of the equivalence.
+	 * The hash need not remain consistent from one execution of an application to
+	 * another execution of the same application.
+	 * <li>It is <i>distributable across equivalence</i>: for any references
+	 * {@code x} and {@code y}, if {@code equivalent(x, y)}, then
+	 * {@code hash(x) == hash(y)}. It is <i>not</i> necessary that the hash be
+	 * distributable across <i>inequivalence</i>. If {@code equivalence(x, y)} is
+	 * false, {@code hash(x) == hash(y)} may still be true.
+	 * <li>{@code hash(null)} is {@code 0}.
+	 * </ul>
+	 */
+	public final int hash(@Nullable T t) {
+		if (t == null) {
+			return 0;
+		}
+		return doHash(t);
+	}
+
+	/**
+	 * Returns a hash code for non-null object {@code t}.
+	 *
+	 * <p>
+	 * Called by {@link #hash}.
+	 *
+	 * @since 10.0 (previously, subclasses would override hash())
+	 */
+	protected abstract int doHash(T t);
+
+	/**
+	 * Returns a new equivalence relation for {@code F} which evaluates equivalence
+	 * by first applying {@code function} to the argument, then evaluating using
+	 * {@code this}. That is, for any pair of non-null objects {@code x} and
+	 * {@code y}, {@code
+	 * equivalence.onResultOf(function).equivalent(a, b)} is true if and only if
+	 * {@code
+	 * equivalence.equivalent(function.apply(a), function.apply(b))} is true.
+	 *
+	 * <p>
+	 * For example:
+	 *
+	 * <pre>
+	 * {
+	 * 	&#64;code
+	 * 	Equivalence<Person> SAME_AGE = Equivalence.equals().onResultOf(GET_PERSON_AGE);
+	 * }
+	 * </pre>
+	 * 
+	 * <p>
+	 * {@code function} will never be invoked with a null value.
+	 * 
+	 * <p>
+	 * Note that {@code function} must be consistent according to {@code this}
+	 * equivalence relation. That is, invoking {@link Function#apply} multiple times
+	 * for a given value must return equivalent results. For example,
+	 * {@code Equivalence.identity().onResultOf(Functions.toStringFunction())} is
+	 * broken because it's not guaranteed that {@link Object#toString}) always
+	 * returns the same string instance.
+	 * 
+	 * @since 10.0
+	 */
+	public final <F> Equivalence<F> onResultOf(Function<F, ? extends T> function) {
+		return new FunctionalEquivalence<F, T>(function, this);
+	}
+
+	/**
+	 * Returns a wrapper of {@code reference} that implements
+	 * {@link Wrapper#equals(Object) Object.equals()} such that
+	 * {@code wrap(a).equals(wrap(b))} if and only if {@code equivalent(a, b)}.
+	 * 
+	 * @since 10.0
+	 */
+	public final <S extends T> Wrapper<S> wrap(@Nullable S reference) {
+		return new Wrapper<S>(this, reference);
+	}
+
+	/**
+	 * Wraps an object so that {@link #equals(Object)} and {@link #hashCode()}
+	 * delegate to an {@link Equivalence}.
+	 *
+	 * <p>
+	 * For example, given an {@link Equivalence} for {@link String strings} named
+	 * {@code equiv} that tests equivalence using their lengths:
+	 *
+	 * <pre>
+	 *    {@code
+	 *   equiv.wrap("a").equals(equiv.wrap("b")) // true
+	 *   equiv.wrap("a").equals(equiv.wrap("hello")) // false}
+	 * </pre>
+	 *
+	 * <p>
+	 * Note in particular that an equivalence wrapper is never equal to the object
+	 * it wraps.
+	 *
+	 * <pre>
+	 *    {@code
+	 *   equiv.wrap(obj).equals(obj) // always false}
+	 * </pre>
+	 *
+	 * @since 10.0
+	 */
+	public static final class Wrapper<T> implements Serializable {
+		private final Equivalence<? super T> equivalence;
+		@Nullable
+		private final T reference;
+
+		private Wrapper(Equivalence<? super T> equivalence, @Nullable T reference) {
+			this.equivalence = checkNotNull(equivalence);
+			this.reference = reference;
+		}
+
+		/** Returns the (possibly null) reference wrapped by this instance. */
+		@Nullable
+		public T get() {
+			return reference;
+		}
+
+		/**
+		 * Returns {@code true} if {@link Equivalence#equivalent(Object, Object)}
+		 * applied to the wrapped references is {@code true} and both wrappers use the
+		 * {@link Object#equals(Object) same} equivalence.
+		 */
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj == this) {
+				return true;
+			}
+			if (obj instanceof Wrapper) {
+				Wrapper<?> that = (Wrapper<?>) obj; // note: not necessarily a Wrapper<T>
+
+				if (this.equivalence.equals(that.equivalence)) {
+					/*
+					 * We'll accept that as sufficient "proof" that either equivalence should be
+					 * able to handle either reference, so it's safe to circumvent compile-time type
+					 * checking.
+					 */
+					@SuppressWarnings("unchecked")
+					Equivalence<Object> equivalence = (Equivalence<Object>) this.equivalence;
+					return equivalence.equivalent(this.reference, that.reference);
+				}
+			}
+			return false;
+		}
+
+		/**
+		 * Returns the result of {@link Equivalence#hash(Object)} applied to the wrapped
+		 * reference.
+		 */
+		@Override
+		public int hashCode() {
+			return equivalence.hash(reference);
+		}
+
+		/**
+		 * Returns a string representation for this equivalence wrapper. The form of
+		 * this string representation is not specified.
+		 */
+		@Override
+		public String toString() {
+			return equivalence + ".wrap(" + reference + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns an equivalence over iterables based on the equivalence of their
+	 * elements. More specifically, two iterables are considered equivalent if they
+	 * both contain the same number of elements, and each pair of corresponding
+	 * elements is equivalent according to {@code this}. Null iterables are
+	 * equivalent to one another.
+	 * 
+	 * <p>
+	 * Note that this method performs a similar function for equivalences as
+	 * {@link com.google.common.collect.Ordering#lexicographical} does for
+	 * orderings.
+	 *
+	 * @since 10.0
+	 */
+	@GwtCompatible(serializable = true)
+	public final <S extends T> Equivalence<Iterable<S>> pairwise() {
+		// Ideally, the returned equivalence would support Iterable<? extends T>.
+		// However,
+		// the need for this is so rare that it's not worth making callers deal with the
+		// ugly wildcard.
+		return new PairwiseEquivalence<S>(this);
+	}
+
+	/**
+	 * Returns a predicate that evaluates to true if and only if the input is
+	 * equivalent to {@code target} according to this equivalence relation.
+	 * 
+	 * @since 10.0
+	 */
+	@Beta
+	public final Predicate<T> equivalentTo(@Nullable T target) {
+		return new EquivalentToPredicate<T>(this, target);
+	}
+
+	private static final class EquivalentToPredicate<T> implements Predicate<T>, Serializable {
+
+		private final Equivalence<T> equivalence;
+		@Nullable
+		private final T target;
+
+		EquivalentToPredicate(Equivalence<T> equivalence, @Nullable T target) {
+			this.equivalence = checkNotNull(equivalence);
+			this.target = target;
+		}
+
+		@Override
+		public boolean apply(@Nullable T input) {
+			return equivalence.equivalent(input, target);
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (this == obj) {
+				return true;
+			}
+			if (obj instanceof EquivalentToPredicate) {
+				EquivalentToPredicate<?> that = (EquivalentToPredicate<?>) obj;
+				return equivalence.equals(that.equivalence) && Objects.equal(target, that.target);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return Objects.hashCode(equivalence, target);
+		}
+
+		@Override
+		public String toString() {
+			return equivalence + ".equivalentTo(" + target + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns an equivalence that delegates to {@link Object#equals} and
+	 * {@link Object#hashCode}. {@link Equivalence#equivalent} returns {@code true}
+	 * if both values are null, or if neither value is null and
+	 * {@link Object#equals} returns {@code true}. {@link Equivalence#hash} returns
+	 * {@code 0} if passed a null value.
+	 *
+	 * @since 13.0
+	 * @since 8.0 (in Equivalences with null-friendly behavior)
+	 * @since 4.0 (in Equivalences)
+	 */
+	public static Equivalence<Object> equals() {
+		return Equals.INSTANCE;
+	}
+
+	/**
+	 * Returns an equivalence that uses {@code ==} to compare values and
+	 * {@link System#identityHashCode(Object)} to compute the hash code.
+	 * {@link Equivalence#equivalent} returns {@code true} if {@code a == b},
+	 * including in the case that a and b are both null.
+	 *
+	 * @since 13.0
+	 * @since 4.0 (in Equivalences)
+	 */
+	public static Equivalence<Object> identity() {
+		return Identity.INSTANCE;
+	}
+
+	static final class Equals extends Equivalence<Object> implements Serializable {
+
+		static final Equals INSTANCE = new Equals();
+
+		@Override
+		protected boolean doEquivalent(Object a, Object b) {
+			return a.equals(b);
+		}
+
+		@Override
+		public int doHash(Object o) {
+			return o.hashCode();
+		}
+
+		private Object readResolve() {
+			return INSTANCE;
+		}
+
+		private static final long serialVersionUID = 1;
+	}
+
+	static final class Identity extends Equivalence<Object> implements Serializable {
+
+		static final Identity INSTANCE = new Identity();
+
+		@Override
+		protected boolean doEquivalent(Object a, Object b) {
+			return false;
+		}
+
+		@Override
+		protected int doHash(Object o) {
+			return System.identityHashCode(o);
+		}
+
+		private Object readResolve() {
+			return INSTANCE;
+		}
+
+		private static final long serialVersionUID = 1;
+	}
+}

sources/main/java/com/google/common/base/FinalizablePhantomReference.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright (C) 2007 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 java.lang.ref.PhantomReference;
+import java.lang.ref.ReferenceQueue;
+
+/**
+ * Phantom reference with a {@code finalizeReferent()} method which a background
+ * thread invokes after the garbage collector reclaims the referent. This is a
+ * simpler alternative to using a {@link ReferenceQueue}.
+ *
+ * <p>
+ * Unlike a normal phantom reference, this reference will be cleared
+ * automatically.
+ *
+ * @author Bob Lee
+ * @since 2.0 (imported from Google Collections Library)
+ */
+public abstract class FinalizablePhantomReference<T> extends PhantomReference<T> implements FinalizableReference {
+	/**
+	 * Constructs a new finalizable phantom reference.
+	 *
+	 * @param referent to phantom reference
+	 * @param queue    that should finalize the referent
+	 */
+	protected FinalizablePhantomReference(T referent, FinalizableReferenceQueue queue) {
+		super(referent, queue.queue);
+		queue.cleanUp();
+	}
+}

sources/main/java/com/google/common/base/FinalizableReference.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (C) 2007 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;
+
+/**
+ * Implemented by references that have code to run after garbage collection of
+ * their referents.
+ *
+ * @see FinalizableReferenceQueue
+ * @author Bob Lee
+ * @since 2.0 (imported from Google Collections Library)
+ */
+public interface FinalizableReference {
+	/**
+	 * Invoked on a background thread after the referent has been garbage collected
+	 * unless security restrictions prevented starting a background thread, in which
+	 * case this method is invoked when new references are created.
+	 */
+	void finalizeReferent();
+}

sources/main/java/com/google/common/base/FinalizableReferenceQueue.java

@@ -0,0 +1,371 @@
+/*
+ * Copyright (C) 2007 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 java.io.Closeable;
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.lang.ref.PhantomReference;
+import java.lang.ref.Reference;
+import java.lang.ref.ReferenceQueue;
+import java.lang.reflect.Method;
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+import com.google.common.annotations.VisibleForTesting;
+
+/**
+ * A reference queue with an associated background thread that dequeues
+ * references and invokes {@link FinalizableReference#finalizeReferent()} on
+ * them.
+ *
+ * <p>
+ * Keep a strong reference to this object until all of the associated referents
+ * have been finalized. If this object is garbage collected earlier, the backing
+ * thread will not invoke {@code
+ * finalizeReferent()} on the remaining references.
+ *
+ * <p>
+ * As an example of how this is used, imagine you have a class {@code MyServer}
+ * that creates a a {@link java.net.ServerSocket ServerSocket}, and you would
+ * like to ensure that the {@code ServerSocket} is closed even if the
+ * {@code MyServer} object is garbage-collected without calling its
+ * {@code close} method. You <em>could</em> use a finalizer to accomplish this,
+ * but that has a number of well-known problems. Here is how you might use this
+ * class instead:
+ *
+ * <pre>
+ * public class MyServer implements Closeable {
+ *   private static final FinalizableReferenceQueue frq = new FinalizableReferenceQueue();
+ *   // You might also share this between several objects.
+ *
+ *   private static final Set&lt;Reference&lt;?>> references = Sets.newConcurrentHashSet();
+ *   // This ensures that the FinalizablePhantomReference itself is not garbage-collected.
+ *
+ *   private final ServerSocket serverSocket;
+ *
+ *   private MyServer(...) {
+ *     ...
+ *     this.serverSocket = new ServerSocket(...);
+ *     ...
+ *   }
+ *
+ *   public static MyServer create(...) {
+ *     MyServer myServer = new MyServer(...);
+ *     final ServerSocket serverSocket = myServer.serverSocket;
+ *     Reference&lt;?> reference = new FinalizablePhantomReference&lt;MyServer>(myServer, frq) {
+ *       &#64;Override public void finalizeReferent() {
+ *         references.remove(this):
+ *         if (!serverSocket.isClosed()) {
+ *           ...log a message about how nobody called close()...
+ *           try {
+ *             serverSocket.close();
+ *           } catch (IOException e) {
+ *             ...
+ *           }
+ *         }
+ *       }
+ *     };
+ *     references.add(reference);
+ *     return myServer;
+ *   }
+ *
+ *   &#64;Override public void close() {
+ *     serverSocket.close();
+ *   }
+ * }
+ * </pre>
+ *
+ * @author Bob Lee
+ * @since 2.0 (imported from Google Collections Library)
+ */
+public class FinalizableReferenceQueue implements Closeable {
+	/*
+	 * The Finalizer thread keeps a phantom reference to this object. When the
+	 * client (for example, a map built by MapMaker) no longer has a strong
+	 * reference to this object, the garbage collector will reclaim it and enqueue
+	 * the phantom reference. The enqueued reference will trigger the Finalizer to
+	 * stop.
+	 *
+	 * If this library is loaded in the system class loader,
+	 * FinalizableReferenceQueue can load Finalizer directly with no problems.
+	 *
+	 * If this library is loaded in an application class loader, it's important that
+	 * Finalizer not have a strong reference back to the class loader. Otherwise,
+	 * you could have a graph like this:
+	 *
+	 * Finalizer Thread runs instance of -> Finalizer.class loaded by -> Application
+	 * class loader which loaded -> ReferenceMap.class which has a static ->
+	 * FinalizableReferenceQueue instance
+	 *
+	 * Even if no other references to classes from the application class loader
+	 * remain, the Finalizer thread keeps an indirect strong reference to the queue
+	 * in ReferenceMap, which keeps the Finalizer running, and as a result, the
+	 * application class loader can never be reclaimed.
+	 *
+	 * This means that dynamically loaded web applications and OSGi bundles can't be
+	 * unloaded.
+	 *
+	 * If the library is loaded in an application class loader, we try to break the
+	 * cycle by loading Finalizer in its own independent class loader:
+	 *
+	 * System class loader -> Application class loader -> ReferenceMap ->
+	 * FinalizableReferenceQueue -> etc. -> Decoupled class loader -> Finalizer
+	 *
+	 * Now, Finalizer no longer keeps an indirect strong reference to the static
+	 * FinalizableReferenceQueue field in ReferenceMap. The application class loader
+	 * can be reclaimed at which point the Finalizer thread will stop and its
+	 * decoupled class loader can also be reclaimed.
+	 *
+	 * If any of this fails along the way, we fall back to loading Finalizer
+	 * directly in the application class loader.
+	 */
+
+	private static final Logger logger = Logger.getLogger(FinalizableReferenceQueue.class.getName());
+
+	private static final String FINALIZER_CLASS_NAME = "com.google.common.base.internal.Finalizer";
+
+	/** Reference to Finalizer.startFinalizer(). */
+	private static final Method startFinalizer;
+	static {
+		Class<?> finalizer = loadFinalizer(new SystemLoader(), new DecoupledLoader(), new DirectLoader());
+		startFinalizer = getStartFinalizer(finalizer);
+	}
+
+	/**
+	 * The actual reference queue that our background thread will poll.
+	 */
+	final ReferenceQueue<Object> queue;
+
+	final PhantomReference<Object> frqRef;
+
+	/**
+	 * Whether or not the background thread started successfully.
+	 */
+	final boolean threadStarted;
+
+	/**
+	 * Constructs a new queue.
+	 */
+	public FinalizableReferenceQueue() {
+		// We could start the finalizer lazily, but I'd rather it blow up early.
+		queue = new ReferenceQueue<Object>();
+		frqRef = new PhantomReference<Object>(this, queue);
+		boolean threadStarted = false;
+		try {
+			startFinalizer.invoke(null, FinalizableReference.class, queue, frqRef);
+			threadStarted = true;
+		} catch (IllegalAccessException impossible) {
+			throw new AssertionError(impossible); // startFinalizer() is public
+		} catch (Throwable t) {
+			logger.log(Level.INFO, "Failed to start reference finalizer thread."
+					+ " Reference cleanup will only occur when new references are created.", t);
+		}
+
+		this.threadStarted = threadStarted;
+	}
+
+	@Override
+	public void close() {
+		frqRef.enqueue();
+		cleanUp();
+	}
+
+	/**
+	 * Repeatedly dequeues references from the queue and invokes
+	 * {@link FinalizableReference#finalizeReferent()} on them until the queue is
+	 * empty. This method is a no-op if the background thread was created
+	 * successfully.
+	 */
+	void cleanUp() {
+		if (threadStarted) {
+			return;
+		}
+
+		Reference<?> reference;
+		while ((reference = queue.poll()) != null) {
+			/*
+			 * This is for the benefit of phantom references. Weak and soft references will
+			 * have already been cleared by this point.
+			 */
+			reference.clear();
+			try {
+				((FinalizableReference) reference).finalizeReferent();
+			} catch (Throwable t) {
+				logger.log(Level.SEVERE, "Error cleaning up after reference.", t);
+			}
+		}
+	}
+
+	/**
+	 * Iterates through the given loaders until it finds one that can load
+	 * Finalizer.
+	 *
+	 * @return Finalizer.class
+	 */
+	private static Class<?> loadFinalizer(FinalizerLoader... loaders) {
+		for (FinalizerLoader loader : loaders) {
+			Class<?> finalizer = loader.loadFinalizer();
+			if (finalizer != null) {
+				return finalizer;
+			}
+		}
+
+		throw new AssertionError();
+	}
+
+	/**
+	 * Loads Finalizer.class.
+	 */
+	interface FinalizerLoader {
+
+		/**
+		 * Returns Finalizer.class or null if this loader shouldn't or can't load it.
+		 *
+		 * @throws SecurityException if we don't have the appropriate privileges
+		 */
+		Class<?> loadFinalizer();
+	}
+
+	/**
+	 * Tries to load Finalizer from the system class loader. If Finalizer is in the
+	 * system class path, we needn't create a separate loader.
+	 */
+	static class SystemLoader implements FinalizerLoader {
+		// This is used by the ClassLoader-leak test in FinalizableReferenceQueueTest to
+		// disable
+		// finding Finalizer on the system class path even if it is there.
+		@VisibleForTesting
+		static boolean disabled;
+
+		@Override
+		public Class<?> loadFinalizer() {
+			if (disabled) {
+				return null;
+			}
+			ClassLoader systemLoader;
+			try {
+				systemLoader = ClassLoader.getSystemClassLoader();
+			} catch (SecurityException e) {
+				logger.info("Not allowed to access system class loader.");
+				return null;
+			}
+			if (systemLoader != null) {
+				try {
+					return systemLoader.loadClass(FINALIZER_CLASS_NAME);
+				} catch (ClassNotFoundException e) {
+					// Ignore. Finalizer is simply in a child class loader.
+					return null;
+				}
+			} else {
+				return null;
+			}
+		}
+	}
+
+	/**
+	 * Try to load Finalizer in its own class loader. If Finalizer's thread had a
+	 * direct reference to our class loader (which could be that of a dynamically
+	 * loaded web application or OSGi bundle), it would prevent our class loader
+	 * from getting garbage collected.
+	 */
+	static class DecoupledLoader implements FinalizerLoader {
+		private static final String LOADING_ERROR = "Could not load Finalizer in its own class loader."
+				+ "Loading Finalizer in the current class loader instead. As a result, you will not be able"
+				+ "to garbage collect this class loader. To support reclaiming this class loader, either"
+				+ "resolve the underlying issue, or move Google Collections to your system class path.";
+
+		@Override
+		public Class<?> loadFinalizer() {
+			try {
+				/*
+				 * We use URLClassLoader because it's the only concrete class loader
+				 * implementation in the JDK. If we used our own ClassLoader subclass, Finalizer
+				 * would indirectly reference this class loader:
+				 *
+				 * Finalizer.class -> CustomClassLoader -> CustomClassLoader.class -> This class
+				 * loader
+				 *
+				 * System class loader will (and must) be the parent.
+				 */
+				ClassLoader finalizerLoader = newLoader(getBaseUrl());
+				return finalizerLoader.loadClass(FINALIZER_CLASS_NAME);
+			} catch (Exception e) {
+				logger.log(Level.WARNING, LOADING_ERROR, e);
+				return null;
+			}
+		}
+
+		/**
+		 * Gets URL for base of path containing Finalizer.class.
+		 */
+		URL getBaseUrl() throws IOException {
+			// Find URL pointing to Finalizer.class file.
+			String finalizerPath = FINALIZER_CLASS_NAME.replace('.', '/') + ".class";
+			URL finalizerUrl = getClass().getClassLoader().getResource(finalizerPath);
+			if (finalizerUrl == null) {
+				throw new FileNotFoundException(finalizerPath);
+			}
+
+			// Find URL pointing to base of class path.
+			String urlString = finalizerUrl.toString();
+			if (!urlString.endsWith(finalizerPath)) {
+				throw new IOException("Unsupported path style: " + urlString);
+			}
+			urlString = urlString.substring(0, urlString.length() - finalizerPath.length());
+			return new URL(finalizerUrl, urlString);
+		}
+
+		/** Creates a class loader with the given base URL as its classpath. */
+		URLClassLoader newLoader(URL base) {
+			// We use the bootstrap class loader as the parent because Finalizer by design
+			// uses
+			// only standard Java classes. That also means that
+			// FinalizableReferenceQueueTest
+			// doesn't pick up the wrong version of the Finalizer class.
+			return new URLClassLoader(new URL[] { base }, null);
+		}
+	}
+
+	/**
+	 * Loads Finalizer directly using the current class loader. We won't be able to
+	 * garbage collect this class loader, but at least the world doesn't end.
+	 */
+	static class DirectLoader implements FinalizerLoader {
+		@Override
+		public Class<?> loadFinalizer() {
+			try {
+				return Class.forName(FINALIZER_CLASS_NAME);
+			} catch (ClassNotFoundException e) {
+				throw new AssertionError(e);
+			}
+		}
+	}
+
+	/**
+	 * Looks up Finalizer.startFinalizer().
+	 */
+	static Method getStartFinalizer(Class<?> finalizer) {
+		try {
+			return finalizer.getMethod("startFinalizer", Class.class, ReferenceQueue.class, PhantomReference.class);
+		} catch (NoSuchMethodException e) {
+			throw new AssertionError(e);
+		}
+	}
+}

sources/main/java/com/google/common/base/FinalizableSoftReference.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2007 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 java.lang.ref.ReferenceQueue;
+import java.lang.ref.SoftReference;
+
+/**
+ * Soft reference with a {@code finalizeReferent()} method which a background
+ * thread invokes after the garbage collector reclaims the referent. This is a
+ * simpler alternative to using a {@link ReferenceQueue}.
+ *
+ * @author Bob Lee
+ * @since 2.0 (imported from Google Collections Library)
+ */
+public abstract class FinalizableSoftReference<T> extends SoftReference<T> implements FinalizableReference {
+	/**
+	 * Constructs a new finalizable soft reference.
+	 *
+	 * @param referent to softly reference
+	 * @param queue    that should finalize the referent
+	 */
+	protected FinalizableSoftReference(T referent, FinalizableReferenceQueue queue) {
+		super(referent, queue.queue);
+		queue.cleanUp();
+	}
+}

sources/main/java/com/google/common/base/FinalizableWeakReference.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2007 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 java.lang.ref.ReferenceQueue;
+import java.lang.ref.WeakReference;
+
+/**
+ * Weak reference with a {@code finalizeReferent()} method which a background
+ * thread invokes after the garbage collector reclaims the referent. This is a
+ * simpler alternative to using a {@link ReferenceQueue}.
+ *
+ * @author Bob Lee
+ * @since 2.0 (imported from Google Collections Library)
+ */
+public abstract class FinalizableWeakReference<T> extends WeakReference<T> implements FinalizableReference {
+	/**
+	 * Constructs a new finalizable weak reference.
+	 *
+	 * @param referent to weakly reference
+	 * @param queue    that should finalize the referent
+	 */
+	protected FinalizableWeakReference(T referent, FinalizableReferenceQueue queue) {
+		super(referent, queue.queue);
+		queue.cleanUp();
+	}
+}

sources/main/java/com/google/common/base/Function.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright (C) 2007 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 javax.annotation.Nullable;
+
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Determines an output value based on an input value.
+ *
+ * <p>
+ * The {@link Functions} class provides common functions and related utilites.
+ *
+ * <p>
+ * See the Guava User Guide article on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/FunctionalExplained">the use
+ * of {@code
+ * Function}</a>.
+ *
+ * @author Kevin Bourrillion
+ * @since 2.0 (imported from Google Collections Library)
+ */
+@GwtCompatible
+public interface Function<F, T> {
+	/**
+	 * Returns the result of applying this function to {@code input}. This method is
+	 * <i>generally expected</i>, but not absolutely required, to have the following
+	 * properties:
+	 *
+	 * <ul>
+	 * <li>Its execution does not cause any observable side effects.
+	 * <li>The computation is <i>consistent with equals</i>; that is,
+	 * {@link Objects#equal Objects.equal}{@code (a, b)} implies that
+	 * {@code Objects.equal(function.apply(a),
+	 *     function.apply(b))}.
+	 * </ul>
+	 *
+	 * @throws NullPointerException if {@code input} is null and this function does
+	 *                              not accept null arguments
+	 */
+	@Nullable
+	T apply(@Nullable F input);
+
+	/**
+	 * Indicates whether another object is equal to this function.
+	 *
+	 * <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 Function} that it considers
+	 * <i>interchangeable</i> with this one. "Interchangeable" <i>typically</i>
+	 * means that {@code Objects.equal(this.apply(f), that.apply(f))} is true for
+	 * all {@code f} of type {@code F}. Note that a {@code false} result from this
+	 * method does not imply that the functions are known <i>not</i> to be
+	 * interchangeable.
+	 */
+	@Override
+	boolean equals(@Nullable Object object);
+}

sources/main/java/com/google/common/base/FunctionalEquivalence.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright (C) 2011 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 javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Equivalence applied on functional result.
+ *
+ * @author Bob Lee
+ * @since 10.0
+ */
+@Beta
+@GwtCompatible
+final class FunctionalEquivalence<F, T> extends Equivalence<F> implements Serializable {
+
+	private static final long serialVersionUID = 0;
+
+	private final Function<F, ? extends T> function;
+	private final Equivalence<T> resultEquivalence;
+
+	FunctionalEquivalence(Function<F, ? extends T> function, Equivalence<T> resultEquivalence) {
+		this.function = checkNotNull(function);
+		this.resultEquivalence = checkNotNull(resultEquivalence);
+	}
+
+	@Override
+	protected boolean doEquivalent(F a, F b) {
+		return resultEquivalence.equivalent(function.apply(a), function.apply(b));
+	}
+
+	@Override
+	protected int doHash(F a) {
+		return resultEquivalence.hash(function.apply(a));
+	}
+
+	@Override
+	public boolean equals(@Nullable Object obj) {
+		if (obj == this) {
+			return true;
+		}
+		if (obj instanceof FunctionalEquivalence) {
+			FunctionalEquivalence<?, ?> that = (FunctionalEquivalence<?, ?>) obj;
+			return function.equals(that.function) && resultEquivalence.equals(that.resultEquivalence);
+		}
+		return false;
+	}
+
+	@Override
+	public int hashCode() {
+		return Objects.hashCode(function, resultEquivalence);
+	}
+
+	@Override
+	public String toString() {
+		return resultEquivalence + ".onResultOf(" + function + ")";
+	}
+}

sources/main/java/com/google/common/base/Functions.java

@@ -0,0 +1,403 @@
+/*
+ * Copyright (C) 2007 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.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import java.io.Serializable;
+import java.util.Map;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Static utility methods pertaining to {@code Function} instances.
+ *
+ * <p>
+ * All methods return serializable functions as long as they're given
+ * serializable parameters.
+ * 
+ * <p>
+ * See the Guava User Guide article on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/FunctionalExplained">the use
+ * of {@code
+ * Function}</a>.
+ *
+ * @author Mike Bostock
+ * @author Jared Levy
+ * @since 2.0 (imported from Google Collections Library)
+ */
+@GwtCompatible
+public final class Functions {
+	private Functions() {
+	}
+
+	/**
+	 * Returns a function that calls {@code toString()} on its argument. The
+	 * function does not accept nulls; it will throw a {@link NullPointerException}
+	 * when applied to {@code null}.
+	 *
+	 * <p>
+	 * <b>Warning:</b> The returned function may not be <i>consistent with
+	 * equals</i> (as documented at {@link Function#apply}). For example, this
+	 * function yields different results for the two equal instances
+	 * {@code ImmutableSet.of(1, 2)} and {@code ImmutableSet.of(2, 1)}.
+	 */
+	public static Function<Object, String> toStringFunction() {
+		return ToStringFunction.INSTANCE;
+	}
+
+	// enum singleton pattern
+	private enum ToStringFunction implements Function<Object, String> {
+		INSTANCE;
+
+		@Override
+		public String apply(Object o) {
+			checkNotNull(o); // eager for GWT.
+			return o.toString();
+		}
+
+		@Override
+		public String toString() {
+			return "toString";
+		}
+	}
+
+	/**
+	 * Returns the identity function.
+	 */
+	// implementation is "fully variant"; E has become a "pass-through" type
+	@SuppressWarnings("unchecked")
+	public static <E> Function<E, E> identity() {
+		return (Function<E, E>) IdentityFunction.INSTANCE;
+	}
+
+	// enum singleton pattern
+	private enum IdentityFunction implements Function<Object, Object> {
+		INSTANCE;
+
+		@Override
+		@Nullable
+		public Object apply(@Nullable Object o) {
+			return o;
+		}
+
+		@Override
+		public String toString() {
+			return "identity";
+		}
+	}
+
+	/**
+	 * Returns a function which performs a map lookup. The returned function throws
+	 * an {@link IllegalArgumentException} if given a key that does not exist in the
+	 * map. See also {@link #forMap(Map, Object)}, which returns a default value in
+	 * this case.
+	 *
+	 * <p>
+	 * Note: if {@code map} is a {@link com.google.common.collect.BiMap BiMap} (or
+	 * can be one), you can use {@link com.google.common.collect.Maps#asConverter
+	 * Maps.asConverter} instead to get a function that also supports reverse
+	 * conversion.
+	 */
+	public static <K, V> Function<K, V> forMap(Map<K, V> map) {
+		return new FunctionForMapNoDefault<K, V>(map);
+	}
+
+	private static class FunctionForMapNoDefault<K, V> implements Function<K, V>, Serializable {
+		final Map<K, V> map;
+
+		FunctionForMapNoDefault(Map<K, V> map) {
+			this.map = checkNotNull(map);
+		}
+
+		@Override
+		public V apply(@Nullable K key) {
+			V result = map.get(key);
+			checkArgument(result != null || map.containsKey(key), "Key '%s' not present in map", key);
+			return result;
+		}
+
+		@Override
+		public boolean equals(@Nullable Object o) {
+			if (o instanceof FunctionForMapNoDefault) {
+				FunctionForMapNoDefault<?, ?> that = (FunctionForMapNoDefault<?, ?>) o;
+				return map.equals(that.map);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return map.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return "forMap(" + map + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns a function which performs a map lookup with a default value. The
+	 * function created by this method returns {@code defaultValue} for all inputs
+	 * that do not belong to the map's key set. See also {@link #forMap(Map)}, which
+	 * throws an exception in this case.
+	 *
+	 * @param map          source map that determines the function behavior
+	 * @param defaultValue the value to return for inputs that aren't map keys
+	 * @return function that returns {@code map.get(a)} when {@code a} is a key, or
+	 *         {@code
+	 *         defaultValue} otherwise
+	 */
+	public static <K, V> Function<K, V> forMap(Map<K, ? extends V> map, @Nullable V defaultValue) {
+		return new ForMapWithDefault<K, V>(map, defaultValue);
+	}
+
+	private static class ForMapWithDefault<K, V> implements Function<K, V>, Serializable {
+		final Map<K, ? extends V> map;
+		final V defaultValue;
+
+		ForMapWithDefault(Map<K, ? extends V> map, @Nullable V defaultValue) {
+			this.map = checkNotNull(map);
+			this.defaultValue = defaultValue;
+		}
+
+		@Override
+		public V apply(@Nullable K key) {
+			V result = map.get(key);
+			return (result != null || map.containsKey(key)) ? result : defaultValue;
+		}
+
+		@Override
+		public boolean equals(@Nullable Object o) {
+			if (o instanceof ForMapWithDefault) {
+				ForMapWithDefault<?, ?> that = (ForMapWithDefault<?, ?>) o;
+				return map.equals(that.map) && Objects.equal(defaultValue, that.defaultValue);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return Objects.hashCode(map, defaultValue);
+		}
+
+		@Override
+		public String toString() {
+			return "forMap(" + map + ", defaultValue=" + defaultValue + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns the composition of two functions. For {@code f: A->B} and
+	 * {@code g: B->C}, composition is defined as the function h such that
+	 * {@code h(a) == g(f(a))} for each {@code a}.
+	 *
+	 * @param g the second function to apply
+	 * @param f the first function to apply
+	 * @return the composition of {@code f} and {@code g}
+	 * @see <a href="//en.wikipedia.org/wiki/Function_composition">function
+	 *      composition</a>
+	 */
+	public static <A, B, C> Function<A, C> compose(Function<B, C> g, Function<A, ? extends B> f) {
+		return new FunctionComposition<A, B, C>(g, f);
+	}
+
+	private static class FunctionComposition<A, B, C> implements Function<A, C>, Serializable {
+		private final Function<B, C> g;
+		private final Function<A, ? extends B> f;
+
+		public FunctionComposition(Function<B, C> g, Function<A, ? extends B> f) {
+			this.g = checkNotNull(g);
+			this.f = checkNotNull(f);
+		}
+
+		@Override
+		public C apply(@Nullable A a) {
+			return g.apply(f.apply(a));
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof FunctionComposition) {
+				FunctionComposition<?, ?, ?> that = (FunctionComposition<?, ?, ?>) obj;
+				return f.equals(that.f) && g.equals(that.g);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return f.hashCode() ^ g.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return g + "(" + f + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Creates a function that returns the same boolean output as the given
+	 * predicate for all inputs.
+	 *
+	 * <p>
+	 * The returned function is <i>consistent with equals</i> (as documented at
+	 * {@link Function#apply}) if and only if {@code predicate} is itself consistent
+	 * with equals.
+	 */
+	public static <T> Function<T, Boolean> forPredicate(Predicate<T> predicate) {
+		return new PredicateFunction<T>(predicate);
+	}
+
+	/** @see Functions#forPredicate */
+	private static class PredicateFunction<T> implements Function<T, Boolean>, Serializable {
+		private final Predicate<T> predicate;
+
+		private PredicateFunction(Predicate<T> predicate) {
+			this.predicate = checkNotNull(predicate);
+		}
+
+		@Override
+		public Boolean apply(@Nullable T t) {
+			return predicate.apply(t);
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof PredicateFunction) {
+				PredicateFunction<?> that = (PredicateFunction<?>) obj;
+				return predicate.equals(that.predicate);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return predicate.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return "forPredicate(" + predicate + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Creates a function that returns {@code value} for any input.
+	 *
+	 * @param value the constant value for the function to return
+	 * @return a function that always returns {@code value}
+	 */
+	public static <E> Function<Object, E> constant(@Nullable E value) {
+		return new ConstantFunction<E>(value);
+	}
+
+	private static class ConstantFunction<E> implements Function<Object, E>, Serializable {
+		private final E value;
+
+		public ConstantFunction(@Nullable E value) {
+			this.value = value;
+		}
+
+		@Override
+		public E apply(@Nullable Object from) {
+			return value;
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof ConstantFunction) {
+				ConstantFunction<?> that = (ConstantFunction<?>) obj;
+				return Objects.equal(value, that.value);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return (value == null) ? 0 : value.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return "constant(" + value + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns a function that always returns the result of invoking
+	 * {@link Supplier#get} on {@code
+	 * supplier}, regardless of its input.
+	 * 
+	 * @since 10.0
+	 */
+	@Beta
+	public static <T> Function<Object, T> forSupplier(Supplier<T> supplier) {
+		return new SupplierFunction<T>(supplier);
+	}
+
+	/** @see Functions#forSupplier */
+	private static class SupplierFunction<T> implements Function<Object, T>, Serializable {
+
+		private final Supplier<T> supplier;
+
+		private SupplierFunction(Supplier<T> supplier) {
+			this.supplier = checkNotNull(supplier);
+		}
+
+		@Override
+		public T apply(@Nullable Object input) {
+			return supplier.get();
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof SupplierFunction) {
+				SupplierFunction<?> that = (SupplierFunction<?>) obj;
+				return this.supplier.equals(that.supplier);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return supplier.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return "forSupplier(" + supplier + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+}

sources/main/java/com/google/common/base/Joiner.java

@@ -0,0 +1,501 @@
+/*
+ * 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.IOException;
+import java.util.AbstractList;
+import java.util.Arrays;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.Map.Entry;
+
+import javax.annotation.CheckReturnValue;
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * An object which joins pieces of text (specified as an array,
+ * {@link Iterable}, varargs or even a {@link Map}) with a separator. It either
+ * appends the results to an {@link Appendable} or returns them as a
+ * {@link String}. Example:
+ * 
+ * <pre>
+ *    {@code
+ *
+ *   Joiner joiner = Joiner.on("; ").skipNulls();
+ *    . . .
+ *   return joiner.join("Harry", null, "Ron", "Hermione");}
+ * </pre>
+ *
+ * <p>
+ * This returns the string {@code "Harry; Ron; Hermione"}. Note that all input
+ * elements are converted to strings using {@link Object#toString()} before
+ * being appended.
+ *
+ * <p>
+ * If neither {@link #skipNulls()} nor {@link #useForNull(String)} is specified,
+ * the joining methods will throw {@link NullPointerException} if any given
+ * element is null.
+ *
+ * <p>
+ * <b>Warning: joiner instances are always immutable</b>; a configuration method
+ * such as {@code
+ * useForNull} has no effect on the instance it is invoked on! You must store
+ * and use the new joiner instance returned by the method. This makes joiners
+ * thread-safe, and safe to store as {@code
+ * static final} constants.
+ * 
+ * <pre>
+ * {
+ * 	&#64;code
+ *
+ * 	// Bad! Do not do this!
+ * 	Joiner joiner = Joiner.on(',');
+ * 	joiner.skipNulls(); // does nothing!
+ * 	return joiner.join("wrong", null, "wrong");
+ * }
+ * </pre>
+ * 
+ * <p>
+ * See the Guava User Guide article on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/StringsExplained#Joiner">{@code Joiner}</a>.
+ *
+ * @author Kevin Bourrillion
+ * @since 2.0 (imported from Google Collections Library)
+ */
+@GwtCompatible
+public class Joiner {
+	/**
+	 * Returns a joiner which automatically places {@code separator} between
+	 * consecutive elements.
+	 */
+	public static Joiner on(String separator) {
+		return new Joiner(separator);
+	}
+
+	/**
+	 * Returns a joiner which automatically places {@code separator} between
+	 * consecutive elements.
+	 */
+	public static Joiner on(char separator) {
+		return new Joiner(String.valueOf(separator));
+	}
+
+	private final String separator;
+
+	private Joiner(String separator) {
+		this.separator = checkNotNull(separator);
+	}
+
+	private Joiner(Joiner prototype) {
+		this.separator = prototype.separator;
+	}
+
+	/**
+	 * Appends the string representation of each of {@code parts}, using the
+	 * previously configured separator between each, to {@code appendable}.
+	 */
+	public <A extends Appendable> A appendTo(A appendable, Iterable<?> parts) throws IOException {
+		return appendTo(appendable, parts.iterator());
+	}
+
+	/**
+	 * Appends the string representation of each of {@code parts}, using the
+	 * previously configured separator between each, to {@code appendable}.
+	 *
+	 * @since 11.0
+	 */
+	public <A extends Appendable> A appendTo(A appendable, Iterator<?> parts) throws IOException {
+		checkNotNull(appendable);
+		if (parts.hasNext()) {
+			appendable.append(toString(parts.next()));
+			while (parts.hasNext()) {
+				appendable.append(separator);
+				appendable.append(toString(parts.next()));
+			}
+		}
+		return appendable;
+	}
+
+	/**
+	 * Appends the string representation of each of {@code parts}, using the
+	 * previously configured separator between each, to {@code appendable}.
+	 */
+	public final <A extends Appendable> A appendTo(A appendable, Object[] parts) throws IOException {
+		return appendTo(appendable, Arrays.asList(parts));
+	}
+
+	/**
+	 * Appends to {@code appendable} the string representation of each of the
+	 * remaining arguments.
+	 */
+	public final <A extends Appendable> A appendTo(A appendable, @Nullable Object first, @Nullable Object second,
+			Object... rest) throws IOException {
+		return appendTo(appendable, iterable(first, second, rest));
+	}
+
+	/**
+	 * Appends the string representation of each of {@code parts}, using the
+	 * previously configured separator between each, to {@code builder}. Identical
+	 * to {@link #appendTo(Appendable, Iterable)}, except that it does not throw
+	 * {@link IOException}.
+	 */
+	public final StringBuilder appendTo(StringBuilder builder, Iterable<?> parts) {
+		return appendTo(builder, parts.iterator());
+	}
+
+	/**
+	 * Appends the string representation of each of {@code parts}, using the
+	 * previously configured separator between each, to {@code builder}. Identical
+	 * to {@link #appendTo(Appendable, Iterable)}, except that it does not throw
+	 * {@link IOException}.
+	 *
+	 * @since 11.0
+	 */
+	public final StringBuilder appendTo(StringBuilder builder, Iterator<?> parts) {
+		try {
+			appendTo((Appendable) builder, parts);
+		} catch (IOException impossible) {
+			throw new AssertionError(impossible);
+		}
+		return builder;
+	}
+
+	/**
+	 * Appends the string representation of each of {@code parts}, using the
+	 * previously configured separator between each, to {@code builder}. Identical
+	 * to {@link #appendTo(Appendable, Iterable)}, except that it does not throw
+	 * {@link IOException}.
+	 */
+	public final StringBuilder appendTo(StringBuilder builder, Object[] parts) {
+		return appendTo(builder, Arrays.asList(parts));
+	}
+
+	/**
+	 * Appends to {@code builder} the string representation of each of the remaining
+	 * arguments. Identical to
+	 * {@link #appendTo(Appendable, Object, Object, Object...)}, except that it does
+	 * not throw {@link IOException}.
+	 */
+	public final StringBuilder appendTo(StringBuilder builder, @Nullable Object first, @Nullable Object second,
+			Object... rest) {
+		return appendTo(builder, iterable(first, second, rest));
+	}
+
+	/**
+	 * Returns a string containing the string representation of each of
+	 * {@code parts}, using the previously configured separator between each.
+	 */
+	public final String join(Iterable<?> parts) {
+		return join(parts.iterator());
+	}
+
+	/**
+	 * Returns a string containing the string representation of each of
+	 * {@code parts}, using the previously configured separator between each.
+	 *
+	 * @since 11.0
+	 */
+	public final String join(Iterator<?> parts) {
+		return appendTo(new StringBuilder(), parts).toString();
+	}
+
+	/**
+	 * Returns a string containing the string representation of each of
+	 * {@code parts}, using the previously configured separator between each.
+	 */
+	public final String join(Object[] parts) {
+		return join(Arrays.asList(parts));
+	}
+
+	/**
+	 * Returns a string containing the string representation of each argument, using
+	 * the previously configured separator between each.
+	 */
+	public final String join(@Nullable Object first, @Nullable Object second, Object... rest) {
+		return join(iterable(first, second, rest));
+	}
+
+	/**
+	 * Returns a joiner with the same behavior as this one, except automatically
+	 * substituting {@code
+	 * nullText} for any provided null elements.
+	 */
+	@CheckReturnValue
+	public Joiner useForNull(final String nullText) {
+		checkNotNull(nullText);
+		return new Joiner(this) {
+			@Override
+			CharSequence toString(@Nullable Object part) {
+				return (part == null) ? nullText : Joiner.this.toString(part);
+			}
+
+			@Override
+			public Joiner useForNull(String nullText) {
+				throw new UnsupportedOperationException("already specified useForNull");
+			}
+
+			@Override
+			public Joiner skipNulls() {
+				throw new UnsupportedOperationException("already specified useForNull");
+			}
+		};
+	}
+
+	/**
+	 * Returns a joiner with the same behavior as this joiner, except automatically
+	 * skipping over any provided null elements.
+	 */
+	@CheckReturnValue
+	public Joiner skipNulls() {
+		return new Joiner(this) {
+			@Override
+			public <A extends Appendable> A appendTo(A appendable, Iterator<?> parts) throws IOException {
+				checkNotNull(appendable, "appendable");
+				checkNotNull(parts, "parts");
+				while (parts.hasNext()) {
+					Object part = parts.next();
+					if (part != null) {
+						appendable.append(Joiner.this.toString(part));
+						break;
+					}
+				}
+				while (parts.hasNext()) {
+					Object part = parts.next();
+					if (part != null) {
+						appendable.append(separator);
+						appendable.append(Joiner.this.toString(part));
+					}
+				}
+				return appendable;
+			}
+
+			@Override
+			public Joiner useForNull(String nullText) {
+				throw new UnsupportedOperationException("already specified skipNulls");
+			}
+
+			@Override
+			public MapJoiner withKeyValueSeparator(String kvs) {
+				throw new UnsupportedOperationException("can't use .skipNulls() with maps");
+			}
+		};
+	}
+
+	/**
+	 * Returns a {@code MapJoiner} using the given key-value separator, and the same
+	 * configuration as this {@code Joiner} otherwise.
+	 */
+	@CheckReturnValue
+	public MapJoiner withKeyValueSeparator(String keyValueSeparator) {
+		return new MapJoiner(this, keyValueSeparator);
+	}
+
+	/**
+	 * An object that joins map entries in the same manner as {@code Joiner} joins
+	 * iterables and arrays. Like {@code Joiner}, it is thread-safe and immutable.
+	 *
+	 * <p>
+	 * In addition to operating on {@code Map} instances, {@code MapJoiner} can
+	 * operate on {@code
+	 * Multimap} entries in two distinct modes:
+	 *
+	 * <ul>
+	 * <li>To output a separate entry for each key-value pair, pass
+	 * {@code multimap.entries()} to a {@code MapJoiner} method that accepts entries
+	 * as input, and receive output of the form {@code key1=A&key1=B&key2=C}.
+	 * <li>To output a single entry for each key, pass {@code multimap.asMap()} to a
+	 * {@code MapJoiner} method that accepts a map as input, and receive output of
+	 * the form {@code
+	 *     key1=[A, B]&key2=C}.
+	 * </ul>
+	 *
+	 * @since 2.0 (imported from Google Collections Library)
+	 */
+	public static final class MapJoiner {
+		private final Joiner joiner;
+		private final String keyValueSeparator;
+
+		private MapJoiner(Joiner joiner, String keyValueSeparator) {
+			this.joiner = joiner; // only "this" is ever passed, so don't checkNotNull
+			this.keyValueSeparator = checkNotNull(keyValueSeparator);
+		}
+
+		/**
+		 * Appends the string representation of each entry of {@code map}, using the
+		 * previously configured separator and key-value separator, to
+		 * {@code appendable}.
+		 */
+		public <A extends Appendable> A appendTo(A appendable, Map<?, ?> map) throws IOException {
+			return appendTo(appendable, map.entrySet());
+		}
+
+		/**
+		 * Appends the string representation of each entry of {@code map}, using the
+		 * previously configured separator and key-value separator, to {@code builder}.
+		 * Identical to {@link #appendTo(Appendable, Map)}, except that it does not
+		 * throw {@link IOException}.
+		 */
+		public StringBuilder appendTo(StringBuilder builder, Map<?, ?> map) {
+			return appendTo(builder, map.entrySet());
+		}
+
+		/**
+		 * Returns a string containing the string representation of each entry of
+		 * {@code map}, using the previously configured separator and key-value
+		 * separator.
+		 */
+		public String join(Map<?, ?> map) {
+			return join(map.entrySet());
+		}
+
+		/**
+		 * Appends the string representation of each entry in {@code entries}, using the
+		 * previously configured separator and key-value separator, to
+		 * {@code appendable}.
+		 *
+		 * @since 10.0
+		 */
+		@Beta
+		public <A extends Appendable> A appendTo(A appendable, Iterable<? extends Entry<?, ?>> entries)
+				throws IOException {
+			return appendTo(appendable, entries.iterator());
+		}
+
+		/**
+		 * Appends the string representation of each entry in {@code entries}, using the
+		 * previously configured separator and key-value separator, to
+		 * {@code appendable}.
+		 *
+		 * @since 11.0
+		 */
+		@Beta
+		public <A extends Appendable> A appendTo(A appendable, Iterator<? extends Entry<?, ?>> parts)
+				throws IOException {
+			checkNotNull(appendable);
+			if (parts.hasNext()) {
+				Entry<?, ?> entry = parts.next();
+				appendable.append(joiner.toString(entry.getKey()));
+				appendable.append(keyValueSeparator);
+				appendable.append(joiner.toString(entry.getValue()));
+				while (parts.hasNext()) {
+					appendable.append(joiner.separator);
+					Entry<?, ?> e = parts.next();
+					appendable.append(joiner.toString(e.getKey()));
+					appendable.append(keyValueSeparator);
+					appendable.append(joiner.toString(e.getValue()));
+				}
+			}
+			return appendable;
+		}
+
+		/**
+		 * Appends the string representation of each entry in {@code entries}, using the
+		 * previously configured separator and key-value separator, to {@code builder}.
+		 * Identical to {@link #appendTo(Appendable, Iterable)}, except that it does not
+		 * throw {@link IOException}.
+		 *
+		 * @since 10.0
+		 */
+		@Beta
+		public StringBuilder appendTo(StringBuilder builder, Iterable<? extends Entry<?, ?>> entries) {
+			return appendTo(builder, entries.iterator());
+		}
+
+		/**
+		 * Appends the string representation of each entry in {@code entries}, using the
+		 * previously configured separator and key-value separator, to {@code builder}.
+		 * Identical to {@link #appendTo(Appendable, Iterable)}, except that it does not
+		 * throw {@link IOException}.
+		 *
+		 * @since 11.0
+		 */
+		@Beta
+		public StringBuilder appendTo(StringBuilder builder, Iterator<? extends Entry<?, ?>> entries) {
+			try {
+				appendTo((Appendable) builder, entries);
+			} catch (IOException impossible) {
+				throw new AssertionError(impossible);
+			}
+			return builder;
+		}
+
+		/**
+		 * Returns a string containing the string representation of each entry in
+		 * {@code entries}, using the previously configured separator and key-value
+		 * separator.
+		 *
+		 * @since 10.0
+		 */
+		@Beta
+		public String join(Iterable<? extends Entry<?, ?>> entries) {
+			return join(entries.iterator());
+		}
+
+		/**
+		 * Returns a string containing the string representation of each entry in
+		 * {@code entries}, using the previously configured separator and key-value
+		 * separator.
+		 *
+		 * @since 11.0
+		 */
+		@Beta
+		public String join(Iterator<? extends Entry<?, ?>> entries) {
+			return appendTo(new StringBuilder(), entries).toString();
+		}
+
+		/**
+		 * Returns a map joiner with the same behavior as this one, except automatically
+		 * substituting {@code nullText} for any provided null keys or values.
+		 */
+		@CheckReturnValue
+		public MapJoiner useForNull(String nullText) {
+			return new MapJoiner(joiner.useForNull(nullText), keyValueSeparator);
+		}
+	}
+
+	CharSequence toString(Object part) {
+		checkNotNull(part); // checkNotNull for GWT (do not optimize).
+		return (part instanceof CharSequence) ? (CharSequence) part : part.toString();
+	}
+
+	private static Iterable<Object> iterable(final Object first, final Object second, final Object[] rest) {
+		checkNotNull(rest);
+		return new AbstractList<Object>() {
+			@Override
+			public int size() {
+				return rest.length + 2;
+			}
+
+			@Override
+			public Object get(int index) {
+				switch (index) {
+				case 0:
+					return first;
+				case 1:
+					return second;
+				default:
+					return rest[index - 2];
+				}
+			}
+		};
+	}
+}

sources/main/java/com/google/common/base/Objects.java

@@ -0,0 +1,448 @@
+/*
+ * Copyright (C) 2007 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.util.Arrays;
+
+import javax.annotation.CheckReturnValue;
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Helper functions that can operate on any {@code Object}.
+ *
+ * <p>
+ * See the Guava User Guide on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/CommonObjectUtilitiesExplained">writing
+ * {@code Object} methods with {@code Objects}</a>.
+ *
+ * @author Laurence Gonsalves
+ * @since 2.0 (imported from Google Collections Library)
+ */
+@GwtCompatible
+public final class Objects {
+	private Objects() {
+	}
+
+	/**
+	 * Determines whether two possibly-null objects are equal. Returns:
+	 *
+	 * <ul>
+	 * <li>{@code true} if {@code a} and {@code b} are both null.
+	 * <li>{@code true} if {@code a} and {@code b} are both non-null and they are
+	 * equal according to {@link Object#equals(Object)}.
+	 * <li>{@code false} in all other situations.
+	 * </ul>
+	 *
+	 * <p>
+	 * This assumes that any non-null objects passed to this function conform to the
+	 * {@code equals()} contract.
+	 */
+	@CheckReturnValue
+	public static boolean equal(@Nullable Object a, @Nullable Object b) {
+		return a == b || (a != null && a.equals(b));
+	}
+
+	/**
+	 * Generates a hash code for multiple values. The hash code is generated by
+	 * calling {@link Arrays#hashCode(Object[])}. Note that array arguments to this
+	 * method, with the exception of a single Object array, do not get any special
+	 * handling; their hash codes are based on identity and not contents.
+	 *
+	 * <p>
+	 * This is useful for implementing {@link Object#hashCode()}. For example, in an
+	 * object that has three properties, {@code x}, {@code y}, and {@code z}, one
+	 * could write:
+	 * 
+	 * <pre>
+	 *    {@code
+	 *   public int hashCode() {
+	 *     return Objects.hashCode(getX(), getY(), getZ());
+	 *   }}
+	 * </pre>
+	 *
+	 * <p>
+	 * <b>Warning</b>: When a single object is supplied, the returned hash code does
+	 * not equal the hash code of that object.
+	 */
+	public static int hashCode(@Nullable Object... objects) {
+		return Arrays.hashCode(objects);
+	}
+
+	/**
+	 * Creates an instance of {@link ToStringHelper}.
+	 *
+	 * <p>
+	 * This is helpful for implementing {@link Object#toString()}. Specification by
+	 * example:
+	 * 
+	 * <pre>
+	 *    {@code
+	 *   // Returns "ClassName{}"
+	 *   Objects.toStringHelper(this)
+	 *       .toString();
+	 *
+	 *   // Returns "ClassName{x=1}"
+	 *   Objects.toStringHelper(this)
+	 *       .add("x", 1)
+	 *       .toString();
+	 *
+	 *   // Returns "MyObject{x=1}"
+	 *   Objects.toStringHelper("MyObject")
+	 *       .add("x", 1)
+	 *       .toString();
+	 *
+	 *   // Returns "ClassName{x=1, y=foo}"
+	 *   Objects.toStringHelper(this)
+	 *       .add("x", 1)
+	 *       .add("y", "foo")
+	 *       .toString();
+	 *
+	 *   // Returns "ClassName{x=1}"
+	 *   Objects.toStringHelper(this)
+	 *       .omitNullValues()
+	 *       .add("x", 1)
+	 *       .add("y", null)
+	 *       .toString();
+	 *   }}
+	 * </pre>
+	 *
+	 * <p>
+	 * Note that in GWT, class names are often obfuscated.
+	 *
+	 * @param self the object to generate the string for (typically {@code this}),
+	 *             used only for its class name
+	 * @since 2.0
+	 */
+	public static ToStringHelper toStringHelper(Object self) {
+		return new ToStringHelper(simpleName(self.getClass()));
+	}
+
+	/**
+	 * Creates an instance of {@link ToStringHelper} in the same manner as
+	 * {@link Objects#toStringHelper(Object)}, but using the name of {@code clazz}
+	 * instead of using an instance's {@link Object#getClass()}.
+	 *
+	 * <p>
+	 * Note that in GWT, class names are often obfuscated.
+	 *
+	 * @param clazz the {@link Class} of the instance
+	 * @since 7.0 (source-compatible since 2.0)
+	 */
+	public static ToStringHelper toStringHelper(Class<?> clazz) {
+		return new ToStringHelper(simpleName(clazz));
+	}
+
+	/**
+	 * Creates an instance of {@link ToStringHelper} in the same manner as
+	 * {@link Objects#toStringHelper(Object)}, but using {@code className} instead
+	 * of using an instance's {@link Object#getClass()}.
+	 *
+	 * @param className the name of the instance type
+	 * @since 7.0 (source-compatible since 2.0)
+	 */
+	public static ToStringHelper toStringHelper(String className) {
+		return new ToStringHelper(className);
+	}
+
+	/**
+	 * {@link Class#getSimpleName()} is not GWT compatible yet, so we provide our
+	 * own implementation.
+	 */
+	private static String simpleName(Class<?> clazz) {
+		String name = clazz.getName();
+
+		// the nth anonymous class has a class name ending in "Outer$n"
+		// and local inner classes have names ending in "Outer.$1Inner"
+		name = name.replaceAll("\\$[0-9]+", "\\$");
+
+		// we want the name of the inner class all by its lonesome
+		int start = name.lastIndexOf('$');
+
+		// if this isn't an inner class, just find the start of the
+		// top level class name.
+		if (start == -1) {
+			start = name.lastIndexOf('.');
+		}
+		return name.substring(start + 1);
+	}
+
+	/**
+	 * Returns the first of two given parameters that is not {@code null}, if either
+	 * is, or otherwise throws a {@link NullPointerException}.
+	 *
+	 * <p>
+	 * <b>Note:</b> if {@code first} is represented as an {@link Optional}, this can
+	 * be accomplished with {@linkplain Optional#or(Object) first.or(second)}. That
+	 * approach also allows for lazy evaluation of the fallback instance, using
+	 * {@linkplain Optional#or(Supplier) first.or(Supplier)}.
+	 *
+	 * @return {@code first} if {@code first} is not {@code null}, or {@code second}
+	 *         if {@code first} is {@code null} and {@code second} is not
+	 *         {@code null}
+	 * @throws NullPointerException if both {@code first} and {@code second} were
+	 *                              {@code null}
+	 * @since 3.0
+	 */
+	public static <T> T firstNonNull(@Nullable T first, @Nullable T second) {
+		return first != null ? first : checkNotNull(second);
+	}
+
+	/**
+	 * Support class for {@link Objects#toStringHelper}.
+	 *
+	 * @author Jason Lee
+	 * @since 2.0
+	 */
+	public static final class ToStringHelper {
+		private final String className;
+		private ValueHolder holderHead = new ValueHolder();
+		private ValueHolder holderTail = holderHead;
+		private boolean omitNullValues = false;
+
+		/**
+		 * Use {@link Objects#toStringHelper(Object)} to create an instance.
+		 */
+		private ToStringHelper(String className) {
+			this.className = checkNotNull(className);
+		}
+
+		/**
+		 * Configures the {@link ToStringHelper} so {@link #toString()} will ignore
+		 * properties with null value. The order of calling this method, relative to the
+		 * {@code add()}/{@code addValue()} methods, is not significant.
+		 *
+		 * @since 12.0
+		 */
+		public ToStringHelper omitNullValues() {
+			omitNullValues = true;
+			return this;
+		}
+
+		/**
+		 * Adds a name/value pair to the formatted output in {@code name=value} format.
+		 * If {@code value} is {@code null}, the string {@code "null"} is used, unless
+		 * {@link #omitNullValues()} is called, in which case this name/value pair will
+		 * not be added.
+		 */
+		public ToStringHelper add(String name, @Nullable Object value) {
+			return addHolder(name, value);
+		}
+
+		/**
+		 * Adds a name/value pair to the formatted output in {@code name=value} format.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper add(String name, boolean value) {
+			return addHolder(name, String.valueOf(value));
+		}
+
+		/**
+		 * Adds a name/value pair to the formatted output in {@code name=value} format.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper add(String name, char value) {
+			return addHolder(name, String.valueOf(value));
+		}
+
+		/**
+		 * Adds a name/value pair to the formatted output in {@code name=value} format.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper add(String name, double value) {
+			return addHolder(name, String.valueOf(value));
+		}
+
+		/**
+		 * Adds a name/value pair to the formatted output in {@code name=value} format.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper add(String name, float value) {
+			return addHolder(name, String.valueOf(value));
+		}
+
+		/**
+		 * Adds a name/value pair to the formatted output in {@code name=value} format.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper add(String name, int value) {
+			return addHolder(name, String.valueOf(value));
+		}
+
+		/**
+		 * Adds a name/value pair to the formatted output in {@code name=value} format.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper add(String name, long value) {
+			return addHolder(name, String.valueOf(value));
+		}
+
+		/**
+		 * Adds an unnamed value to the formatted output.
+		 *
+		 * <p>
+		 * It is strongly encouraged to use {@link #add(String, Object)} instead and
+		 * give value a readable name.
+		 */
+		public ToStringHelper addValue(@Nullable Object value) {
+			return addHolder(value);
+		}
+
+		/**
+		 * Adds an unnamed value to the formatted output.
+		 *
+		 * <p>
+		 * It is strongly encouraged to use {@link #add(String, boolean)} instead and
+		 * give value a readable name.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper addValue(boolean value) {
+			return addHolder(String.valueOf(value));
+		}
+
+		/**
+		 * Adds an unnamed value to the formatted output.
+		 *
+		 * <p>
+		 * It is strongly encouraged to use {@link #add(String, char)} instead and give
+		 * value a readable name.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper addValue(char value) {
+			return addHolder(String.valueOf(value));
+		}
+
+		/**
+		 * Adds an unnamed value to the formatted output.
+		 *
+		 * <p>
+		 * It is strongly encouraged to use {@link #add(String, double)} instead and
+		 * give value a readable name.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper addValue(double value) {
+			return addHolder(String.valueOf(value));
+		}
+
+		/**
+		 * Adds an unnamed value to the formatted output.
+		 *
+		 * <p>
+		 * It is strongly encouraged to use {@link #add(String, float)} instead and give
+		 * value a readable name.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper addValue(float value) {
+			return addHolder(String.valueOf(value));
+		}
+
+		/**
+		 * Adds an unnamed value to the formatted output.
+		 *
+		 * <p>
+		 * It is strongly encouraged to use {@link #add(String, int)} instead and give
+		 * value a readable name.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper addValue(int value) {
+			return addHolder(String.valueOf(value));
+		}
+
+		/**
+		 * Adds an unnamed value to the formatted output.
+		 *
+		 * <p>
+		 * It is strongly encouraged to use {@link #add(String, long)} instead and give
+		 * value a readable name.
+		 *
+		 * @since 11.0 (source-compatible since 2.0)
+		 */
+		public ToStringHelper addValue(long value) {
+			return addHolder(String.valueOf(value));
+		}
+
+		/**
+		 * Returns a string in the format specified by
+		 * {@link Objects#toStringHelper(Object)}.
+		 *
+		 * <p>
+		 * After calling this method, you can keep adding more properties to later call
+		 * toString() again and get a more complete representation of the same object;
+		 * but properties cannot be removed, so this only allows limited reuse of the
+		 * helper instance. The helper allows duplication of properties (multiple
+		 * name/value pairs with the same name can be added).
+		 */
+		@Override
+		public String toString() {
+			// create a copy to keep it consistent in case value changes
+			boolean omitNullValuesSnapshot = omitNullValues;
+			String nextSeparator = "";
+			StringBuilder builder = new StringBuilder(32).append(className).append('{');
+			for (ValueHolder valueHolder = holderHead.next; valueHolder != null; valueHolder = valueHolder.next) {
+				if (!omitNullValuesSnapshot || valueHolder.value != null) {
+					builder.append(nextSeparator);
+					nextSeparator = ", ";
+
+					if (valueHolder.name != null) {
+						builder.append(valueHolder.name).append('=');
+					}
+					builder.append(valueHolder.value);
+				}
+			}
+			return builder.append('}').toString();
+		}
+
+		private ValueHolder addHolder() {
+			ValueHolder valueHolder = new ValueHolder();
+			holderTail = holderTail.next = valueHolder;
+			return valueHolder;
+		}
+
+		private ToStringHelper addHolder(@Nullable Object value) {
+			ValueHolder valueHolder = addHolder();
+			valueHolder.value = value;
+			return this;
+		}
+
+		private ToStringHelper addHolder(String name, @Nullable Object value) {
+			ValueHolder valueHolder = addHolder();
+			valueHolder.value = value;
+			valueHolder.name = checkNotNull(name);
+			return this;
+		}
+
+		private static final class ValueHolder {
+			String name;
+			Object value;
+			ValueHolder next;
+		}
+	}
+}

sources/main/java/com/google/common/base/Optional.java

@@ -0,0 +1,265 @@
+/*
+ * Copyright (C) 2011 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 java.util.Set;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * An immutable object that may contain a non-null reference to another object.
+ * Each instance of this type either contains a non-null reference, or contains
+ * nothing (in which case we say that the reference is "absent"); it is never
+ * said to "contain {@code
+ * null}".
+ *
+ * <p>
+ * A non-null {@code Optional<T>} reference can be used as a replacement for a
+ * nullable {@code T} reference. It allows you to represent "a {@code T} that
+ * must be present" and a "a {@code T} that might be absent" as two distinct
+ * types in your program, which can aid clarity.
+ *
+ * <p>
+ * Some uses of this class include
+ *
+ * <ul>
+ * <li>As a method return type, as an alternative to returning {@code null} to
+ * indicate that no value was available
+ * <li>To distinguish between "unknown" (for example, not present in a map) and
+ * "known to have no value" (present in the map, with value
+ * {@code Optional.absent()})
+ * <li>To wrap nullable references for storage in a collection that does not
+ * support {@code null} (though there are <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/LivingWithNullHostileCollections">
+ * several other approaches to this</a> that should be considered first)
+ * </ul>
+ *
+ * <p>
+ * A common alternative to using this class is to find or create a suitable
+ * <a href="http://en.wikipedia.org/wiki/Null_Object_pattern">null object</a>
+ * for the type in question.
+ *
+ * <p>
+ * This class is not intended as a direct analogue of any existing "option" or
+ * "maybe" construct from other programming environments, though it may bear
+ * some similarities.
+ *
+ * <p>
+ * See the Guava User Guide article on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/UsingAndAvoidingNullExplained#Optional">
+ * using {@code Optional}</a>.
+ *
+ * @param <T> the type of instance that can be contained. {@code Optional} is
+ *            naturally covariant on this type, so it is safe to cast an
+ *            {@code Optional<T>} to {@code
+ *     Optional<S>} for any supertype {@code S} of {@code T}.
+ * @author Kurt Alfred Kluever
+ * @author Kevin Bourrillion
+ * @since 10.0
+ */
+@GwtCompatible(serializable = true)
+public abstract class Optional<T> implements Serializable {
+	/**
+	 * Returns an {@code Optional} instance with no contained reference.
+	 */
+	public static <T> Optional<T> absent() {
+		return Absent.withType();
+	}
+
+	/**
+	 * Returns an {@code Optional} instance containing the given non-null reference.
+	 */
+	public static <T> Optional<T> of(T reference) {
+		return new Present<T>(checkNotNull(reference));
+	}
+
+	/**
+	 * If {@code nullableReference} is non-null, returns an {@code Optional}
+	 * instance containing that reference; otherwise returns
+	 * {@link Optional#absent}.
+	 */
+	public static <T> Optional<T> fromNullable(@Nullable T nullableReference) {
+		return (nullableReference == null) ? Optional.<T>absent() : new Present<T>(nullableReference);
+	}
+
+	Optional() {
+	}
+
+	/**
+	 * Returns {@code true} if this holder contains a (non-null) instance.
+	 */
+	public abstract boolean isPresent();
+
+	/**
+	 * Returns the contained instance, which must be present. If the instance might
+	 * be absent, use {@link #or(Object)} or {@link #orNull} instead.
+	 *
+	 * @throws IllegalStateException if the instance is absent ({@link #isPresent}
+	 *                               returns {@code false})
+	 */
+	public abstract T get();
+
+	/**
+	 * Returns the contained instance if it is present; {@code defaultValue}
+	 * otherwise. If no default value should be required because the instance is
+	 * known to be present, use {@link #get()} instead. For a default value of
+	 * {@code null}, use {@link #orNull}.
+	 *
+	 * <p>
+	 * Note about generics: The signature {@code public T or(T defaultValue)} is
+	 * overly restrictive. However, the ideal signature,
+	 * {@code public <S super T> S or(S)}, is not legal Java. As a result, some
+	 * sensible operations involving subtypes are compile errors:
+	 * 
+	 * <pre>
+	 *    {@code
+	 *
+	 *   Optional<Integer> optionalInt = getSomeOptionalInt();
+	 *   Number value = optionalInt.or(0.5); // error
+	 *
+	 *   FluentIterable<? extends Number> numbers = getSomeNumbers();
+	 *   Optional<? extends Number> first = numbers.first();
+	 *   Number value = first.or(0.5); // error}
+	 * </pre>
+	 *
+	 * <p>
+	 * As a workaround, it is always safe to cast an {@code Optional<? extends T>}
+	 * to {@code
+	 * Optional<T>}. Casting either of the above example {@code Optional} instances
+	 * to {@code
+	 * Optional<Number>} (where {@code Number} is the desired output type) solves
+	 * the problem:
+	 * 
+	 * <pre>
+	 *    {@code
+	 *
+	 *   Optional<Number> optionalInt = (Optional) getSomeOptionalInt();
+	 *   Number value = optionalInt.or(0.5); // fine
+	 *
+	 *   FluentIterable<? extends Number> numbers = getSomeNumbers();
+	 *   Optional<Number> first = (Optional) numbers.first();
+	 *   Number value = first.or(0.5); // fine}
+	 * </pre>
+	 */
+	public abstract T or(T defaultValue);
+
+	/**
+	 * Returns this {@code Optional} if it has a value present; {@code secondChoice}
+	 * otherwise.
+	 */
+	public abstract Optional<T> or(Optional<? extends T> secondChoice);
+
+	/**
+	 * Returns the contained instance if it is present; {@code supplier.get()}
+	 * otherwise. If the supplier returns {@code null}, a
+	 * {@link NullPointerException} is thrown.
+	 *
+	 * @throws NullPointerException if the supplier returns {@code null}
+	 */
+	@Beta
+	public abstract T or(Supplier<? extends T> supplier);
+
+	/**
+	 * Returns the contained instance if it is present; {@code null} otherwise. If
+	 * the instance is known to be present, use {@link #get()} instead.
+	 */
+	@Nullable
+	public abstract T orNull();
+
+	/**
+	 * Returns an immutable singleton {@link Set} whose only element is the
+	 * contained instance if it is present; an empty immutable {@link Set}
+	 * otherwise.
+	 *
+	 * @since 11.0
+	 */
+	public abstract Set<T> asSet();
+
+	/**
+	 * If the instance is present, it is transformed with the given
+	 * {@link Function}; otherwise, {@link Optional#absent} is returned. If the
+	 * function returns {@code null}, a {@link NullPointerException} is thrown.
+	 *
+	 * @throws NullPointerException if the function returns {@code null}
+	 *
+	 * @since 12.0
+	 */
+	public abstract <V> Optional<V> transform(Function<? super T, V> function);
+
+	/**
+	 * Returns {@code true} if {@code object} is an {@code Optional} instance, and
+	 * either the contained references are {@linkplain Object#equals equal} to each
+	 * other or both are absent. Note that {@code Optional} instances of differing
+	 * parameterized types can be equal.
+	 */
+	@Override
+	public abstract boolean equals(@Nullable Object object);
+
+	/**
+	 * Returns a hash code for this instance.
+	 */
+	@Override
+	public abstract int hashCode();
+
+	/**
+	 * Returns a string representation for this instance. The form of this string
+	 * representation is unspecified.
+	 */
+	@Override
+	public abstract String toString();
+
+	/**
+	 * Returns the value of each present instance from the supplied
+	 * {@code optionals}, in order, skipping over occurrences of
+	 * {@link Optional#absent}. Iterators are unmodifiable and are evaluated lazily.
+	 *
+	 * @since 11.0 (generics widened in 13.0)
+	 */
+	@Beta
+	public static <T> Iterable<T> presentInstances(final Iterable<? extends Optional<? extends T>> optionals) {
+		checkNotNull(optionals);
+		return new Iterable<T>() {
+			@Override
+			public Iterator<T> iterator() {
+				return new AbstractIterator<T>() {
+					private final Iterator<? extends Optional<? extends T>> iterator = checkNotNull(
+							optionals.iterator());
+
+					@Override
+					protected T computeNext() {
+						while (iterator.hasNext()) {
+							Optional<? extends T> optional = iterator.next();
+							if (optional.isPresent()) {
+								return optional.get();
+							}
+						}
+						return endOfData();
+					}
+				};
+			}
+		};
+	}
+
+	private static final long serialVersionUID = 0;
+}

sources/main/java/com/google/common/base/PairwiseEquivalence.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright (C) 2011 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 java.io.Serializable;
+import java.util.Iterator;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.GwtCompatible;
+
+@GwtCompatible(serializable = true)
+final class PairwiseEquivalence<T> extends Equivalence<Iterable<T>> implements Serializable {
+
+	final Equivalence<? super T> elementEquivalence;
+
+	PairwiseEquivalence(Equivalence<? super T> elementEquivalence) {
+		this.elementEquivalence = Preconditions.checkNotNull(elementEquivalence);
+	}
+
+	@Override
+	protected boolean doEquivalent(Iterable<T> iterableA, Iterable<T> iterableB) {
+		Iterator<T> iteratorA = iterableA.iterator();
+		Iterator<T> iteratorB = iterableB.iterator();
+
+		while (iteratorA.hasNext() && iteratorB.hasNext()) {
+			if (!elementEquivalence.equivalent(iteratorA.next(), iteratorB.next())) {
+				return false;
+			}
+		}
+
+		return !iteratorA.hasNext() && !iteratorB.hasNext();
+	}
+
+	@Override
+	protected int doHash(Iterable<T> iterable) {
+		int hash = 78721;
+		for (T element : iterable) {
+			hash = hash * 24943 + elementEquivalence.hash(element);
+		}
+		return hash;
+	}
+
+	@Override
+	public boolean equals(@Nullable Object object) {
+		if (object instanceof PairwiseEquivalence) {
+			PairwiseEquivalence<?> that = (PairwiseEquivalence<?>) object;
+			return this.elementEquivalence.equals(that.elementEquivalence);
+		}
+
+		return false;
+	}
+
+	@Override
+	public int hashCode() {
+		return elementEquivalence.hashCode() ^ 0x46a3eb07;
+	}
+
+	@Override
+	public String toString() {
+		return elementEquivalence + ".pairwise()";
+	}
+
+	private static final long serialVersionUID = 1;
+}

sources/main/java/com/google/common/base/Platform.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (C) 2009 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 java.lang.ref.WeakReference;
+
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Methods factored out so that they can be emulated differently in GWT.
+ *
+ * @author Jesse Wilson
+ */
+@GwtCompatible(emulated = true)
+final class Platform {
+	private Platform() {
+	}
+
+	/** Calls {@link System#nanoTime()}. */
+	static long systemNanoTime() {
+		return System.nanoTime();
+	}
+
+	static CharMatcher precomputeCharMatcher(CharMatcher matcher) {
+		return matcher.precomputedInternal();
+	}
+
+	static <T extends Enum<T>> Optional<T> getEnumIfPresent(Class<T> enumClass, String value) {
+		WeakReference<? extends Enum<?>> ref = Enums.getEnumConstants(enumClass).get(value);
+		return ref == null ? Optional.<T>absent() : Optional.of(enumClass.cast(ref.get()));
+	}
+}

sources/main/java/com/google/common/base/Preconditions.java

@@ -0,0 +1,505 @@
+/*
+ * Copyright (C) 2007 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 javax.annotation.Nullable;
+
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Static convenience methods that help a method or constructor check whether it
+ * was invoked correctly (whether its <i>preconditions</i> have been met). These
+ * methods generally accept a {@code boolean} expression which is expected to be
+ * {@code true} (or in the case of {@code
+ * checkNotNull}, an object reference which is expected to be non-null). When
+ * {@code false} (or {@code null}) is passed instead, the {@code Preconditions}
+ * method throws an unchecked exception, which helps the calling method
+ * communicate to <i>its</i> caller that <i>that</i> caller has made a mistake.
+ * Example:
+ * 
+ * <pre>
+ *    {@code
+ *
+ *   /**
+ *    * Returns the positive square root of the given value.
+ *    *
+ *    * @throws IllegalArgumentException if the value is negative
+ *    *}{@code /
+ *   public static double sqrt(double value) {
+ *     Preconditions.checkArgument(value >= 0.0, "negative value: %s", value);
+ *     // calculate the square root
+ *   }
+ *
+ *   void exampleBadCaller() {
+ *     double d = sqrt(-1.0);
+ *   }}
+ * </pre>
+ *
+ * In this example, {@code checkArgument} throws an
+ * {@code IllegalArgumentException} to indicate that {@code exampleBadCaller}
+ * made an error in <i>its</i> call to {@code sqrt}.
+ *
+ * <h3>Warning about performance</h3>
+ *
+ * <p>
+ * The goal of this class is to improve readability of code, but in some
+ * circumstances this may come at a significant performance cost. Remember that
+ * parameter values for message construction must all be computed eagerly, and
+ * autoboxing and varargs array creation may happen as well, even when the
+ * precondition check then succeeds (as it should almost always do in
+ * production). In some circumstances these wasted CPU cycles and allocations
+ * can add up to a real problem. Performance-sensitive precondition checks can
+ * always be converted to the customary form:
+ * 
+ * <pre>
+ *    {@code
+ *
+ *   if (value < 0.0) {
+ *     throw new IllegalArgumentException("negative value: " + value);
+ *   }}
+ * </pre>
+ *
+ * <h3>Other types of preconditions</h3>
+ *
+ * <p>
+ * Not every type of precondition failure is supported by these methods.
+ * Continue to throw standard JDK exceptions such as
+ * {@link java.util.NoSuchElementException} or
+ * {@link UnsupportedOperationException} in the situations they are intended
+ * for.
+ *
+ * <h3>Non-preconditions</h3>
+ *
+ * <p>
+ * It is of course possible to use the methods of this class to check for
+ * invalid conditions which are <i>not the caller's fault</i>. Doing so is
+ * <b>not recommended</b> because it is misleading to future readers of the code
+ * and of stack traces. See <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/ConditionalFailuresExplained">Conditional
+ * failures explained</a> in the Guava User Guide for more advice.
+ *
+ * <h3>{@code java.util.Objects.requireNonNull()}</h3>
+ *
+ * <p>
+ * Projects which use {@code com.google.common} should generally avoid the use
+ * of {@link java.util.Objects#requireNonNull(Object)}. Instead, use whichever
+ * of {@link #checkNotNull(Object)} or {@link Verify#verifyNotNull(Object)} is
+ * appropriate to the situation. (The same goes for the message-accepting
+ * overloads.)
+ *
+ * <h3>Only {@code %s} is supported</h3>
+ *
+ * <p>
+ * In {@code Preconditions} error message template strings, only the
+ * {@code "%s"} specifier is supported, not the full range of
+ * {@link java.util.Formatter} specifiers. However, note that if the number of
+ * arguments does not match the number of occurrences of {@code "%s"} in the
+ * format string, {@code Preconditions} will still behave as expected, and will
+ * still include all argument values in the error message; the message will
+ * simply not be formatted exactly as intended.
+ *
+ * <h3>More information</h3>
+ *
+ * <p>
+ * See the Guava User Guide on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/PreconditionsExplained">using
+ * {@code
+ * Preconditions}</a>.
+ *
+ * @author Kevin Bourrillion
+ * @since 2.0 (imported from Google Collections Library)
+ */
+@GwtCompatible
+public final class Preconditions {
+	private Preconditions() {
+	}
+
+	/**
+	 * Ensures the truth of an expression involving one or more parameters to the
+	 * calling method.
+	 *
+	 * @param expression a boolean expression
+	 * @throws IllegalArgumentException if {@code expression} is false
+	 */
+	public static void checkArgument(boolean expression) {
+		if (!expression) {
+			throw new IllegalArgumentException();
+		}
+	}
+
+	/**
+	 * Ensures the truth of an expression involving one or more parameters to the
+	 * calling method.
+	 *
+	 * @param expression   a boolean expression
+	 * @param errorMessage the exception message to use if the check fails; will be
+	 *                     converted to a string using
+	 *                     {@link String#valueOf(Object)}
+	 * @throws IllegalArgumentException if {@code expression} is false
+	 */
+	public static void checkArgument(boolean expression, @Nullable Object errorMessage) {
+		if (!expression) {
+			throw new IllegalArgumentException(String.valueOf(errorMessage));
+		}
+	}
+
+	/**
+	 * Ensures the truth of an expression involving one or more parameters to the
+	 * calling method.
+	 *
+	 * @param expression           a boolean expression
+	 * @param errorMessageTemplate a template for the exception message should the
+	 *                             check fail. The message is formed by replacing
+	 *                             each {@code %s} placeholder in the template with
+	 *                             an argument. These are matched by position - the
+	 *                             first {@code %s} gets {@code
+	 *     errorMessageArgs[0]} , etc. Unmatched arguments will be appended to
+	 *                             the formatted message in square braces. Unmatched
+	 *                             placeholders will be left as-is.
+	 * @param errorMessageArgs     the arguments to be substituted into the message
+	 *                             template. Arguments are converted to strings
+	 *                             using {@link String#valueOf(Object)}.
+	 * @throws IllegalArgumentException if {@code expression} is false
+	 * @throws NullPointerException     if the check fails and either
+	 *                                  {@code errorMessageTemplate} or
+	 *                                  {@code errorMessageArgs} is null (don't let
+	 *                                  this happen)
+	 */
+	public static void checkArgument(boolean expression, @Nullable String errorMessageTemplate,
+			@Nullable Object... errorMessageArgs) {
+		if (!expression) {
+			throw new IllegalArgumentException(format(errorMessageTemplate, errorMessageArgs));
+		}
+	}
+
+	/**
+	 * Ensures the truth of an expression involving the state of the calling
+	 * instance, but not involving any parameters to the calling method.
+	 *
+	 * @param expression a boolean expression
+	 * @throws IllegalStateException if {@code expression} is false
+	 */
+	public static void checkState(boolean expression) {
+		if (!expression) {
+			throw new IllegalStateException();
+		}
+	}
+
+	/**
+	 * Ensures the truth of an expression involving the state of the calling
+	 * instance, but not involving any parameters to the calling method.
+	 *
+	 * @param expression   a boolean expression
+	 * @param errorMessage the exception message to use if the check fails; will be
+	 *                     converted to a string using
+	 *                     {@link String#valueOf(Object)}
+	 * @throws IllegalStateException if {@code expression} is false
+	 */
+	public static void checkState(boolean expression, @Nullable Object errorMessage) {
+		if (!expression) {
+			throw new IllegalStateException(String.valueOf(errorMessage));
+		}
+	}
+
+	/**
+	 * Ensures the truth of an expression involving the state of the calling
+	 * instance, but not involving any parameters to the calling method.
+	 *
+	 * @param expression           a boolean expression
+	 * @param errorMessageTemplate a template for the exception message should the
+	 *                             check fail. The message is formed by replacing
+	 *                             each {@code %s} placeholder in the template with
+	 *                             an argument. These are matched by position - the
+	 *                             first {@code %s} gets {@code
+	 *     errorMessageArgs[0]} , etc. Unmatched arguments will be appended to
+	 *                             the formatted message in square braces. Unmatched
+	 *                             placeholders will be left as-is.
+	 * @param errorMessageArgs     the arguments to be substituted into the message
+	 *                             template. Arguments are converted to strings
+	 *                             using {@link String#valueOf(Object)}.
+	 * @throws IllegalStateException if {@code expression} is false
+	 * @throws NullPointerException  if the check fails and either
+	 *                               {@code errorMessageTemplate} or
+	 *                               {@code errorMessageArgs} is null (don't let
+	 *                               this happen)
+	 */
+	public static void checkState(boolean expression, @Nullable String errorMessageTemplate,
+			@Nullable Object... errorMessageArgs) {
+		if (!expression) {
+			throw new IllegalStateException(format(errorMessageTemplate, errorMessageArgs));
+		}
+	}
+
+	/**
+	 * Ensures that an object reference passed as a parameter to the calling method
+	 * is not null.
+	 *
+	 * @param reference an object reference
+	 * @return the non-null reference that was validated
+	 * @throws NullPointerException if {@code reference} is null
+	 */
+	public static <T> T checkNotNull(T reference) {
+		if (reference == null) {
+			throw new NullPointerException();
+		}
+		return reference;
+	}
+
+	/**
+	 * Ensures that an object reference passed as a parameter to the calling method
+	 * is not null.
+	 *
+	 * @param reference    an object reference
+	 * @param errorMessage the exception message to use if the check fails; will be
+	 *                     converted to a string using
+	 *                     {@link String#valueOf(Object)}
+	 * @return the non-null reference that was validated
+	 * @throws NullPointerException if {@code reference} is null
+	 */
+	public static <T> T checkNotNull(T reference, @Nullable Object errorMessage) {
+		if (reference == null) {
+			throw new NullPointerException(String.valueOf(errorMessage));
+		}
+		return reference;
+	}
+
+	/**
+	 * Ensures that an object reference passed as a parameter to the calling method
+	 * is not null.
+	 *
+	 * @param reference            an object reference
+	 * @param errorMessageTemplate a template for the exception message should the
+	 *                             check fail. The message is formed by replacing
+	 *                             each {@code %s} placeholder in the template with
+	 *                             an argument. These are matched by position - the
+	 *                             first {@code %s} gets {@code
+	 *     errorMessageArgs[0]} , etc. Unmatched arguments will be appended to
+	 *                             the formatted message in square braces. Unmatched
+	 *                             placeholders will be left as-is.
+	 * @param errorMessageArgs     the arguments to be substituted into the message
+	 *                             template. Arguments are converted to strings
+	 *                             using {@link String#valueOf(Object)}.
+	 * @return the non-null reference that was validated
+	 * @throws NullPointerException if {@code reference} is null
+	 */
+	public static <T> T checkNotNull(T reference, @Nullable String errorMessageTemplate,
+			@Nullable Object... errorMessageArgs) {
+		if (reference == null) {
+			// If either of these parameters is null, the right thing happens anyway
+			throw new NullPointerException(format(errorMessageTemplate, errorMessageArgs));
+		}
+		return reference;
+	}
+
+	/*
+	 * All recent hotspots (as of 2009) *really* like to have the natural code
+	 *
+	 * if (guardExpression) { throw new BadException(messageExpression); }
+	 *
+	 * refactored so that messageExpression is moved to a separate String-returning
+	 * method.
+	 *
+	 * if (guardExpression) { throw new BadException(badMsg(...)); }
+	 *
+	 * The alternative natural refactorings into void or Exception-returning methods
+	 * are much slower. This is a big deal - we're talking factors of 2-8 in
+	 * microbenchmarks, not just 10-20%. (This is a hotspot optimizer bug, which
+	 * should be fixed, but that's a separate, big project).
+	 *
+	 * The coding pattern above is heavily used in java.util, e.g. in ArrayList.
+	 * There is a RangeCheckMicroBenchmark in the JDK that was used to test this.
+	 *
+	 * But the methods in this class want to throw different exceptions, depending
+	 * on the args, so it appears that this pattern is not directly applicable. But
+	 * we can use the ridiculous, devious trick of throwing an exception in the
+	 * middle of the construction of another exception. Hotspot is fine with that.
+	 */
+
+	/**
+	 * Ensures that {@code index} specifies a valid <i>element</i> in an array, list
+	 * or string of size {@code size}. An element index may range from zero,
+	 * inclusive, to {@code size}, exclusive.
+	 *
+	 * @param index a user-supplied index identifying an element of an array, list
+	 *              or string
+	 * @param size  the size of that array, list or string
+	 * @return the value of {@code index}
+	 * @throws IndexOutOfBoundsException if {@code index} is negative or is not less
+	 *                                   than {@code size}
+	 * @throws IllegalArgumentException  if {@code size} is negative
+	 */
+	public static int checkElementIndex(int index, int size) {
+		return checkElementIndex(index, size, "index");
+	}
+
+	/**
+	 * Ensures that {@code index} specifies a valid <i>element</i> in an array, list
+	 * or string of size {@code size}. An element index may range from zero,
+	 * inclusive, to {@code size}, exclusive.
+	 *
+	 * @param index a user-supplied index identifying an element of an array, list
+	 *              or string
+	 * @param size  the size of that array, list or string
+	 * @param desc  the text to use to describe this index in an error message
+	 * @return the value of {@code index}
+	 * @throws IndexOutOfBoundsException if {@code index} is negative or is not less
+	 *                                   than {@code size}
+	 * @throws IllegalArgumentException  if {@code size} is negative
+	 */
+	public static int checkElementIndex(int index, int size, @Nullable String desc) {
+		// Carefully optimized for execution by hotspot (explanatory comment above)
+		if (index < 0 || index >= size) {
+			throw new IndexOutOfBoundsException(badElementIndex(index, size, desc));
+		}
+		return index;
+	}
+
+	private static String badElementIndex(int index, int size, String desc) {
+		if (index < 0) {
+			return format("%s (%s) must not be negative", desc, index);
+		} else if (size < 0) {
+			throw new IllegalArgumentException("negative size: " + size);
+		} else { // index >= size
+			return format("%s (%s) must be less than size (%s)", desc, index, size);
+		}
+	}
+
+	/**
+	 * Ensures that {@code index} specifies a valid <i>position</i> in an array,
+	 * list or string of size {@code size}. A position index may range from zero to
+	 * {@code size}, inclusive.
+	 *
+	 * @param index a user-supplied index identifying a position in an array, list
+	 *              or string
+	 * @param size  the size of that array, list or string
+	 * @return the value of {@code index}
+	 * @throws IndexOutOfBoundsException if {@code index} is negative or is greater
+	 *                                   than {@code size}
+	 * @throws IllegalArgumentException  if {@code size} is negative
+	 */
+	public static int checkPositionIndex(int index, int size) {
+		return checkPositionIndex(index, size, "index");
+	}
+
+	/**
+	 * Ensures that {@code index} specifies a valid <i>position</i> in an array,
+	 * list or string of size {@code size}. A position index may range from zero to
+	 * {@code size}, inclusive.
+	 *
+	 * @param index a user-supplied index identifying a position in an array, list
+	 *              or string
+	 * @param size  the size of that array, list or string
+	 * @param desc  the text to use to describe this index in an error message
+	 * @return the value of {@code index}
+	 * @throws IndexOutOfBoundsException if {@code index} is negative or is greater
+	 *                                   than {@code size}
+	 * @throws IllegalArgumentException  if {@code size} is negative
+	 */
+	public static int checkPositionIndex(int index, int size, @Nullable String desc) {
+		// Carefully optimized for execution by hotspot (explanatory comment above)
+		if (index < 0 || index > size) {
+			throw new IndexOutOfBoundsException(badPositionIndex(index, size, desc));
+		}
+		return index;
+	}
+
+	private static String badPositionIndex(int index, int size, String desc) {
+		if (index < 0) {
+			return format("%s (%s) must not be negative", desc, index);
+		} else if (size < 0) {
+			throw new IllegalArgumentException("negative size: " + size);
+		} else { // index > size
+			return format("%s (%s) must not be greater than size (%s)", desc, index, size);
+		}
+	}
+
+	/**
+	 * Ensures that {@code start} and {@code end} specify a valid <i>positions</i>
+	 * in an array, list or string of size {@code size}, and are in order. A
+	 * position index may range from zero to {@code size}, inclusive.
+	 *
+	 * @param start a user-supplied index identifying a starting position in an
+	 *              array, list or string
+	 * @param end   a user-supplied index identifying a ending position in an array,
+	 *              list or string
+	 * @param size  the size of that array, list or string
+	 * @throws IndexOutOfBoundsException if either index is negative or is greater
+	 *                                   than {@code size}, or if {@code end} is
+	 *                                   less than {@code start}
+	 * @throws IllegalArgumentException  if {@code size} is negative
+	 */
+	public static void checkPositionIndexes(int start, int end, int size) {
+		// Carefully optimized for execution by hotspot (explanatory comment above)
+		if (start < 0 || end < start || end > size) {
+			throw new IndexOutOfBoundsException(badPositionIndexes(start, end, size));
+		}
+	}
+
+	private static String badPositionIndexes(int start, int end, int size) {
+		if (start < 0 || start > size) {
+			return badPositionIndex(start, size, "start index");
+		}
+		if (end < 0 || end > size) {
+			return badPositionIndex(end, size, "end index");
+		}
+		// end < start
+		return format("end index (%s) must not be less than start index (%s)", end, start);
+	}
+
+	/**
+	 * Substitutes each {@code %s} in {@code template} with an argument. These are
+	 * matched by position: the first {@code %s} gets {@code args[0]}, etc. If there
+	 * are more arguments than placeholders, the unmatched arguments will be
+	 * appended to the end of the formatted message in square braces.
+	 *
+	 * @param template a non-null string containing 0 or more {@code %s}
+	 *                 placeholders.
+	 * @param args     the arguments to be substituted into the message template.
+	 *                 Arguments are converted to strings using
+	 *                 {@link String#valueOf(Object)}. Arguments can be null.
+	 */
+	// Note that this is somewhat-improperly used from Verify.java as well.
+	static String format(String template, @Nullable Object... args) {
+		template = String.valueOf(template); // null -> "null"
+
+		// start substituting the arguments into the '%s' placeholders
+		StringBuilder builder = new StringBuilder(template.length() + 16 * args.length);
+		int templateStart = 0;
+		int i = 0;
+		while (i < args.length) {
+			int placeholderStart = template.indexOf("%s", templateStart);
+			if (placeholderStart == -1) {
+				break;
+			}
+			builder.append(template.substring(templateStart, placeholderStart));
+			builder.append(args[i++]);
+			templateStart = placeholderStart + 2;
+		}
+		builder.append(template.substring(templateStart));
+
+		// if we run out of placeholders, append the extra args in square braces
+		if (i < args.length) {
+			builder.append(" [");
+			builder.append(args[i++]);
+			while (i < args.length) {
+				builder.append(", ");
+				builder.append(args[i++]);
+			}
+			builder.append(']');
+		}
+
+		return builder.toString();
+	}
+}

sources/main/java/com/google/common/base/Predicate.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright (C) 2007 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 javax.annotation.Nullable;
+
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Determines a true or false value for a given input.
+ *
+ * <p>
+ * The {@link Predicates} class provides common predicates and related
+ * utilities.
+ *
+ * <p>
+ * See the Guava User Guide article on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/FunctionalExplained">the use
+ * of {@code
+ * Predicate}</a>.
+ *
+ * @author Kevin Bourrillion
+ * @since 2.0 (imported from Google Collections Library)
+ */
+@GwtCompatible
+public interface Predicate<T> {
+	/**
+	 * Returns the result of applying this predicate to {@code input}. This method
+	 * is <i>generally expected</i>, but not absolutely required, to have the
+	 * following properties:
+	 *
+	 * <ul>
+	 * <li>Its execution does not cause any observable side effects.
+	 * <li>The computation is <i>consistent with equals</i>; that is,
+	 * {@link Objects#equal Objects.equal}{@code (a, b)} implies that
+	 * {@code predicate.apply(a) ==
+	 *     predicate.apply(b))}.
+	 * </ul>
+	 *
+	 * @throws NullPointerException if {@code input} is null and this predicate does
+	 *                              not accept null arguments
+	 */
+	boolean apply(@Nullable T input);
+
+	/**
+	 * Indicates whether another object is equal to this predicate.
+	 *
+	 * <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 Predicate} that it considers
+	 * <i>interchangeable</i> with this one. "Interchangeable" <i>typically</i>
+	 * means that {@code this.apply(t) == that.apply(t)} for all {@code t} of type
+	 * {@code T}). Note that a {@code false} result from this method does not imply
+	 * that the predicates are known <i>not</i> to be interchangeable.
+	 */
+	@Override
+	boolean equals(@Nullable Object object);
+}

sources/main/java/com/google/common/base/Predicates.java

@@ -0,0 +1,710 @@
+/*
+ * Copyright (C) 2007 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.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.List;
+import java.util.regex.Pattern;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+import com.google.common.annotations.GwtIncompatible;
+
+/**
+ * Static utility methods pertaining to {@code Predicate} instances.
+ *
+ * <p>
+ * All methods returns serializable predicates as long as they're given
+ * serializable parameters.
+ *
+ * <p>
+ * See the Guava User Guide article on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/FunctionalExplained">the use
+ * of {@code Predicate}</a>.
+ *
+ * @author Kevin Bourrillion
+ * @since 2.0 (imported from Google Collections Library)
+ */
+@GwtCompatible(emulated = true)
+public final class Predicates {
+	private Predicates() {
+	}
+
+	// TODO(kevinb): considering having these implement a VisitablePredicate
+	// interface which specifies an accept(PredicateVisitor) method.
+
+	/**
+	 * Returns a predicate that always evaluates to {@code true}.
+	 */
+	@GwtCompatible(serializable = true)
+	public static <T> Predicate<T> alwaysTrue() {
+		return ObjectPredicate.ALWAYS_TRUE.withNarrowedType();
+	}
+
+	/**
+	 * Returns a predicate that always evaluates to {@code false}.
+	 */
+	@GwtCompatible(serializable = true)
+	public static <T> Predicate<T> alwaysFalse() {
+		return ObjectPredicate.ALWAYS_FALSE.withNarrowedType();
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if the object reference
+	 * being tested is null.
+	 */
+	@GwtCompatible(serializable = true)
+	public static <T> Predicate<T> isNull() {
+		return ObjectPredicate.IS_NULL.withNarrowedType();
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if the object reference
+	 * being tested is not null.
+	 */
+	@GwtCompatible(serializable = true)
+	public static <T> Predicate<T> notNull() {
+		return ObjectPredicate.NOT_NULL.withNarrowedType();
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if the given predicate
+	 * evaluates to {@code false}.
+	 */
+	public static <T> Predicate<T> not(Predicate<T> predicate) {
+		return new NotPredicate<T>(predicate);
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if each of its components
+	 * evaluates to {@code true}. The components are evaluated in order, and
+	 * evaluation will be "short-circuited" as soon as a false predicate is found.
+	 * It defensively copies the iterable passed in, so future changes to it won't
+	 * alter the behavior of this predicate. If {@code
+	 * components} is empty, the returned predicate will always evaluate to {@code
+	 * true}.
+	 */
+	public static <T> Predicate<T> and(Iterable<? extends Predicate<? super T>> components) {
+		return new AndPredicate<T>(defensiveCopy(components));
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if each of its components
+	 * evaluates to {@code true}. The components are evaluated in order, and
+	 * evaluation will be "short-circuited" as soon as a false predicate is found.
+	 * It defensively copies the array passed in, so future changes to it won't
+	 * alter the behavior of this predicate. If {@code
+	 * components} is empty, the returned predicate will always evaluate to {@code
+	 * true}.
+	 */
+	public static <T> Predicate<T> and(Predicate<? super T>... components) {
+		return new AndPredicate<T>(defensiveCopy(components));
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if both of its components
+	 * evaluate to {@code true}. The components are evaluated in order, and
+	 * evaluation will be "short-circuited" as soon as a false predicate is found.
+	 */
+	public static <T> Predicate<T> and(Predicate<? super T> first, Predicate<? super T> second) {
+		return new AndPredicate<T>(Predicates.<T>asList(checkNotNull(first), checkNotNull(second)));
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if any one of its
+	 * components evaluates to {@code true}. The components are evaluated in order,
+	 * and evaluation will be "short-circuited" as soon as a true predicate is
+	 * found. It defensively copies the iterable passed in, so future changes to it
+	 * won't alter the behavior of this predicate. If {@code
+	 * components} is empty, the returned predicate will always evaluate to {@code
+	 * false}.
+	 */
+	public static <T> Predicate<T> or(Iterable<? extends Predicate<? super T>> components) {
+		return new OrPredicate<T>(defensiveCopy(components));
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if any one of its
+	 * components evaluates to {@code true}. The components are evaluated in order,
+	 * and evaluation will be "short-circuited" as soon as a true predicate is
+	 * found. It defensively copies the array passed in, so future changes to it
+	 * won't alter the behavior of this predicate. If {@code
+	 * components} is empty, the returned predicate will always evaluate to {@code
+	 * false}.
+	 */
+	public static <T> Predicate<T> or(Predicate<? super T>... components) {
+		return new OrPredicate<T>(defensiveCopy(components));
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if either of its
+	 * components evaluates to {@code true}. The components are evaluated in order,
+	 * and evaluation will be "short-circuited" as soon as a true predicate is
+	 * found.
+	 */
+	public static <T> Predicate<T> or(Predicate<? super T> first, Predicate<? super T> second) {
+		return new OrPredicate<T>(Predicates.<T>asList(checkNotNull(first), checkNotNull(second)));
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if the object being tested
+	 * {@code equals()} the given target or both are null.
+	 */
+	public static <T> Predicate<T> equalTo(@Nullable T target) {
+		return (target == null) ? Predicates.<T>isNull() : new IsEqualToPredicate<T>(target);
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if the object being tested
+	 * is an instance of the given class. If the object being tested is {@code null}
+	 * this predicate evaluates to {@code false}.
+	 *
+	 * <p>
+	 * If you want to filter an {@code Iterable} to narrow its type, consider using
+	 * {@link com.google.common.collect.Iterables#filter(Iterable, Class)} in
+	 * preference.
+	 *
+	 * <p>
+	 * <b>Warning:</b> contrary to the typical assumptions about predicates (as
+	 * documented at {@link Predicate#apply}), the returned predicate may not be
+	 * <i>consistent with equals</i>. For example, {@code
+	 * instanceOf(ArrayList.class)} will yield different results for the two equal
+	 * instances {@code Lists.newArrayList(1)} and {@code Arrays.asList(1)}.
+	 */
+	@GwtIncompatible("Class.isInstance")
+	public static Predicate<Object> instanceOf(Class<?> clazz) {
+		return new InstanceOfPredicate(clazz);
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if the class being tested
+	 * is assignable from the given class. The returned predicate does not allow
+	 * null inputs.
+	 *
+	 * @since 10.0
+	 */
+	@GwtIncompatible("Class.isAssignableFrom")
+	@Beta
+	public static Predicate<Class<?>> assignableFrom(Class<?> clazz) {
+		return new AssignableFromPredicate(clazz);
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if the object reference
+	 * being tested is a member of the given collection. It does not defensively
+	 * copy the collection passed in, so future changes to it will alter the
+	 * behavior of the predicate.
+	 *
+	 * <p>
+	 * This method can technically accept any {@code Collection<?>}, but using a
+	 * typed collection helps prevent bugs. This approach doesn't block any
+	 * potential users since it is always possible to use {@code
+	 * Predicates.<Object>in()}.
+	 *
+	 * @param target the collection that may contain the function input
+	 */
+	public static <T> Predicate<T> in(Collection<? extends T> target) {
+		return new InPredicate<T>(target);
+	}
+
+	/**
+	 * Returns the composition of a function and a predicate. For every {@code x},
+	 * the generated predicate returns {@code predicate(function(x))}.
+	 *
+	 * @return the composition of the provided function and predicate
+	 */
+	public static <A, B> Predicate<A> compose(Predicate<B> predicate, Function<A, ? extends B> function) {
+		return new CompositionPredicate<A, B>(predicate, function);
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if the
+	 * {@code CharSequence} being tested contains any match for the given regular
+	 * expression pattern. The test used is equivalent to
+	 * {@code Pattern.compile(pattern).matcher(arg).find()}
+	 *
+	 * @throws java.util.regex.PatternSyntaxException if the pattern is invalid
+	 * @since 3.0
+	 */
+	@GwtIncompatible(value = "java.util.regex.Pattern")
+	public static Predicate<CharSequence> containsPattern(String pattern) {
+		return new ContainsPatternFromStringPredicate(pattern);
+	}
+
+	/**
+	 * Returns a predicate that evaluates to {@code true} if the
+	 * {@code CharSequence} being tested contains any match for the given regular
+	 * expression pattern. The test used is equivalent to
+	 * {@code pattern.matcher(arg).find()}
+	 *
+	 * @since 3.0
+	 */
+	@GwtIncompatible(value = "java.util.regex.Pattern")
+	public static Predicate<CharSequence> contains(Pattern pattern) {
+		return new ContainsPatternPredicate(pattern);
+	}
+
+	// End public API, begin private implementation classes.
+
+	// Package private for GWT serialization.
+	enum ObjectPredicate implements Predicate<Object> {
+		/** @see Predicates#alwaysTrue() */
+		ALWAYS_TRUE {
+			@Override
+			public boolean apply(@Nullable Object o) {
+				return true;
+			}
+
+			@Override
+			public String toString() {
+				return "Predicates.alwaysTrue()";
+			}
+		},
+		/** @see Predicates#alwaysFalse() */
+		ALWAYS_FALSE {
+			@Override
+			public boolean apply(@Nullable Object o) {
+				return false;
+			}
+
+			@Override
+			public String toString() {
+				return "Predicates.alwaysFalse()";
+			}
+		},
+		/** @see Predicates#isNull() */
+		IS_NULL {
+			@Override
+			public boolean apply(@Nullable Object o) {
+				return o == null;
+			}
+
+			@Override
+			public String toString() {
+				return "Predicates.isNull()";
+			}
+		},
+		/** @see Predicates#notNull() */
+		NOT_NULL {
+			@Override
+			public boolean apply(@Nullable Object o) {
+				return o != null;
+			}
+
+			@Override
+			public String toString() {
+				return "Predicates.notNull()";
+			}
+		};
+
+		@SuppressWarnings("unchecked") // safe contravariant cast
+		<T> Predicate<T> withNarrowedType() {
+			return (Predicate<T>) this;
+		}
+	}
+
+	/** @see Predicates#not(Predicate) */
+	private static class NotPredicate<T> implements Predicate<T>, Serializable {
+		final Predicate<T> predicate;
+
+		NotPredicate(Predicate<T> predicate) {
+			this.predicate = checkNotNull(predicate);
+		}
+
+		@Override
+		public boolean apply(@Nullable T t) {
+			return !predicate.apply(t);
+		}
+
+		@Override
+		public int hashCode() {
+			return ~predicate.hashCode();
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof NotPredicate) {
+				NotPredicate<?> that = (NotPredicate<?>) obj;
+				return predicate.equals(that.predicate);
+			}
+			return false;
+		}
+
+		@Override
+		public String toString() {
+			return "Predicates.not(" + predicate.toString() + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	private static final Joiner COMMA_JOINER = Joiner.on(',');
+
+	/** @see Predicates#and(Iterable) */
+	private static class AndPredicate<T> implements Predicate<T>, Serializable {
+		private final List<? extends Predicate<? super T>> components;
+
+		private AndPredicate(List<? extends Predicate<? super T>> components) {
+			this.components = components;
+		}
+
+		@Override
+		public boolean apply(@Nullable T t) {
+			// Avoid using the Iterator to avoid generating garbage (issue 820).
+			for (int i = 0; i < components.size(); i++) {
+				if (!components.get(i).apply(t)) {
+					return false;
+				}
+			}
+			return true;
+		}
+
+		@Override
+		public int hashCode() {
+			// add a random number to avoid collisions with OrPredicate
+			return components.hashCode() + 0x12472c2c;
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof AndPredicate) {
+				AndPredicate<?> that = (AndPredicate<?>) obj;
+				return components.equals(that.components);
+			}
+			return false;
+		}
+
+		@Override
+		public String toString() {
+			return "Predicates.and(" + COMMA_JOINER.join(components) + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/** @see Predicates#or(Iterable) */
+	private static class OrPredicate<T> implements Predicate<T>, Serializable {
+		private final List<? extends Predicate<? super T>> components;
+
+		private OrPredicate(List<? extends Predicate<? super T>> components) {
+			this.components = components;
+		}
+
+		@Override
+		public boolean apply(@Nullable T t) {
+			// Avoid using the Iterator to avoid generating garbage (issue 820).
+			for (int i = 0; i < components.size(); i++) {
+				if (components.get(i).apply(t)) {
+					return true;
+				}
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			// add a random number to avoid collisions with AndPredicate
+			return components.hashCode() + 0x053c91cf;
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof OrPredicate) {
+				OrPredicate<?> that = (OrPredicate<?>) obj;
+				return components.equals(that.components);
+			}
+			return false;
+		}
+
+		@Override
+		public String toString() {
+			return "Predicates.or(" + COMMA_JOINER.join(components) + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/** @see Predicates#equalTo(Object) */
+	private static class IsEqualToPredicate<T> implements Predicate<T>, Serializable {
+		private final T target;
+
+		private IsEqualToPredicate(T target) {
+			this.target = target;
+		}
+
+		@Override
+		public boolean apply(T t) {
+			return target.equals(t);
+		}
+
+		@Override
+		public int hashCode() {
+			return target.hashCode();
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof IsEqualToPredicate) {
+				IsEqualToPredicate<?> that = (IsEqualToPredicate<?>) obj;
+				return target.equals(that.target);
+			}
+			return false;
+		}
+
+		@Override
+		public String toString() {
+			return "Predicates.equalTo(" + target + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/** @see Predicates#instanceOf(Class) */
+	@GwtIncompatible("Class.isInstance")
+	private static class InstanceOfPredicate implements Predicate<Object>, Serializable {
+		private final Class<?> clazz;
+
+		private InstanceOfPredicate(Class<?> clazz) {
+			this.clazz = checkNotNull(clazz);
+		}
+
+		@Override
+		public boolean apply(@Nullable Object o) {
+			return clazz.isInstance(o);
+		}
+
+		@Override
+		public int hashCode() {
+			return clazz.hashCode();
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof InstanceOfPredicate) {
+				InstanceOfPredicate that = (InstanceOfPredicate) obj;
+				return clazz == that.clazz;
+			}
+			return false;
+		}
+
+		@Override
+		public String toString() {
+			return "Predicates.instanceOf(" + clazz.getName() + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/** @see Predicates#assignableFrom(Class) */
+	@GwtIncompatible("Class.isAssignableFrom")
+	private static class AssignableFromPredicate implements Predicate<Class<?>>, Serializable {
+		private final Class<?> clazz;
+
+		private AssignableFromPredicate(Class<?> clazz) {
+			this.clazz = checkNotNull(clazz);
+		}
+
+		@Override
+		public boolean apply(Class<?> input) {
+			return clazz.isAssignableFrom(input);
+		}
+
+		@Override
+		public int hashCode() {
+			return clazz.hashCode();
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof AssignableFromPredicate) {
+				AssignableFromPredicate that = (AssignableFromPredicate) obj;
+				return clazz == that.clazz;
+			}
+			return false;
+		}
+
+		@Override
+		public String toString() {
+			return "Predicates.assignableFrom(" + clazz.getName() + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/** @see Predicates#in(Collection) */
+	private static class InPredicate<T> implements Predicate<T>, Serializable {
+		private final Collection<?> target;
+
+		private InPredicate(Collection<?> target) {
+			this.target = checkNotNull(target);
+		}
+
+		@Override
+		public boolean apply(@Nullable T t) {
+			try {
+				return target.contains(t);
+			} catch (NullPointerException e) {
+				return false;
+			} catch (ClassCastException e) {
+				return false;
+			}
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof InPredicate) {
+				InPredicate<?> that = (InPredicate<?>) obj;
+				return target.equals(that.target);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return target.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return "Predicates.in(" + target + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/** @see Predicates#compose(Predicate, Function) */
+	private static class CompositionPredicate<A, B> implements Predicate<A>, Serializable {
+		final Predicate<B> p;
+		final Function<A, ? extends B> f;
+
+		private CompositionPredicate(Predicate<B> p, Function<A, ? extends B> f) {
+			this.p = checkNotNull(p);
+			this.f = checkNotNull(f);
+		}
+
+		@Override
+		public boolean apply(@Nullable A a) {
+			return p.apply(f.apply(a));
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof CompositionPredicate) {
+				CompositionPredicate<?, ?> that = (CompositionPredicate<?, ?>) obj;
+				return f.equals(that.f) && p.equals(that.p);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return f.hashCode() ^ p.hashCode();
+		}
+
+		@Override
+		public String toString() {
+			return p.toString() + "(" + f.toString() + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/** @see Predicates#contains(Pattern) */
+	@GwtIncompatible("Only used by other GWT-incompatible code.")
+	private static class ContainsPatternPredicate implements Predicate<CharSequence>, Serializable {
+		final Pattern pattern;
+
+		ContainsPatternPredicate(Pattern pattern) {
+			this.pattern = checkNotNull(pattern);
+		}
+
+		@Override
+		public boolean apply(CharSequence t) {
+			return pattern.matcher(t).find();
+		}
+
+		@Override
+		public int hashCode() {
+			// Pattern uses Object.hashCode, so we have to reach
+			// inside to build a hashCode consistent with equals.
+
+			return Objects.hashCode(pattern.pattern(), pattern.flags());
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof ContainsPatternPredicate) {
+				ContainsPatternPredicate that = (ContainsPatternPredicate) obj;
+
+				// Pattern uses Object (identity) equality, so we have to reach
+				// inside to compare individual fields.
+				return Objects.equal(pattern.pattern(), that.pattern.pattern())
+						&& Objects.equal(pattern.flags(), that.pattern.flags());
+			}
+			return false;
+		}
+
+		@Override
+		public String toString() {
+			String patternString = Objects.toStringHelper(pattern).add("pattern", pattern.pattern())
+					.add("pattern.flags", pattern.flags()).toString();
+			return "Predicates.contains(" + patternString + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/** @see Predicates#containsPattern(String) */
+	@GwtIncompatible("Only used by other GWT-incompatible code.")
+	private static class ContainsPatternFromStringPredicate extends ContainsPatternPredicate {
+
+		ContainsPatternFromStringPredicate(String string) {
+			super(Pattern.compile(string));
+		}
+
+		@Override
+		public String toString() {
+			return "Predicates.containsPattern(" + pattern.pattern() + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	private static <T> List<Predicate<? super T>> asList(Predicate<? super T> first, Predicate<? super T> second) {
+		// TODO(kevinb): understand why we still get a warning despite @SafeVarargs!
+		return Arrays.<Predicate<? super T>>asList(first, second);
+	}
+
+	private static <T> List<T> defensiveCopy(T... array) {
+		return defensiveCopy(Arrays.asList(array));
+	}
+
+	static <T> List<T> defensiveCopy(Iterable<T> iterable) {
+		ArrayList<T> list = new ArrayList<T>();
+		for (T element : iterable) {
+			list.add(checkNotNull(element));
+		}
+		return list;
+	}
+}

sources/main/java/com/google/common/base/Present.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright (C) 2011 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.util.Collections;
+import java.util.Set;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Implementation of an {@link Optional} containing a reference.
+ */
+@GwtCompatible
+final class Present<T> extends Optional<T> {
+	private final T reference;
+
+	Present(T reference) {
+		this.reference = reference;
+	}
+
+	@Override
+	public boolean isPresent() {
+		return true;
+	}
+
+	@Override
+	public T get() {
+		return reference;
+	}
+
+	@Override
+	public T or(T defaultValue) {
+		checkNotNull(defaultValue, "use Optional.orNull() instead of Optional.or(null)");
+		return reference;
+	}
+
+	@Override
+	public Optional<T> or(Optional<? extends T> secondChoice) {
+		checkNotNull(secondChoice);
+		return this;
+	}
+
+	@Override
+	public T or(Supplier<? extends T> supplier) {
+		checkNotNull(supplier);
+		return reference;
+	}
+
+	@Override
+	public T orNull() {
+		return reference;
+	}
+
+	@Override
+	public Set<T> asSet() {
+		return Collections.singleton(reference);
+	}
+
+	@Override
+	public <V> Optional<V> transform(Function<? super T, V> function) {
+		return new Present<V>(checkNotNull(function.apply(reference),
+				"the Function passed to Optional.transform() must not return null."));
+	}
+
+	@Override
+	public boolean equals(@Nullable Object object) {
+		if (object instanceof Present) {
+			Present<?> other = (Present<?>) object;
+			return reference.equals(other.reference);
+		}
+		return false;
+	}
+
+	@Override
+	public int hashCode() {
+		return 0x598df91c + reference.hashCode();
+	}
+
+	@Override
+	public String toString() {
+		return "Optional.of(" + reference + ")";
+	}
+
+	private static final long serialVersionUID = 0;
+}

sources/main/java/com/google/common/base/SmallCharMatcher.java

@@ -0,0 +1,155 @@
+/*
+ * Copyright (C) 2012 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 java.util.BitSet;
+
+import com.google.common.annotations.GwtIncompatible;
+import com.google.common.annotations.VisibleForTesting;
+import com.google.common.base.CharMatcher.FastMatcher;
+
+/**
+ * An immutable version of CharMatcher for smallish sets of characters that uses
+ * a hash table with linear probing to check for matches.
+ *
+ * @author Christopher Swenson
+ */
+@GwtIncompatible("no precomputation is done in GWT")
+final class SmallCharMatcher extends FastMatcher {
+	static final int MAX_SIZE = 1023;
+	private final char[] table;
+	private final boolean containsZero;
+	private final long filter;
+
+	private SmallCharMatcher(char[] table, long filter, boolean containsZero, String description) {
+		super(description);
+		this.table = table;
+		this.filter = filter;
+		this.containsZero = containsZero;
+	}
+
+	private static final int C1 = 0xcc9e2d51;
+	private static final int C2 = 0x1b873593;
+
+	/*
+	 * This method was rewritten in Java from an intermediate step of the Murmur
+	 * hash function in
+	 * http://code.google.com/p/smhasher/source/browse/trunk/MurmurHash3.cpp, which
+	 * contained the following header:
+	 *
+	 * MurmurHash3 was written by Austin Appleby, and is placed in the public
+	 * domain. The author hereby disclaims copyright to this source code.
+	 */
+	static int smear(int hashCode) {
+		return C2 * Integer.rotateLeft(hashCode * C1, 15);
+	}
+
+	private boolean checkFilter(int c) {
+		return 1 == (1 & (filter >> c));
+	}
+
+	// This is all essentially copied from ImmutableSet, but we have to duplicate
+	// because
+	// of dependencies.
+
+	// Represents how tightly we can pack things, as a maximum.
+	private static final double DESIRED_LOAD_FACTOR = 0.5;
+
+	/**
+	 * Returns an array size suitable for the backing array of a hash table that
+	 * uses open addressing with linear probing in its implementation. The returned
+	 * size is the smallest power of two that can hold setSize elements with the
+	 * desired load factor.
+	 */
+	@VisibleForTesting
+	static int chooseTableSize(int setSize) {
+		if (setSize == 1) {
+			return 2;
+		}
+		// Correct the size for open addressing to match desired load factor.
+		// Round up to the next highest power of 2.
+		int tableSize = Integer.highestOneBit(setSize - 1) << 1;
+		while (tableSize * DESIRED_LOAD_FACTOR < setSize) {
+			tableSize <<= 1;
+		}
+		return tableSize;
+	}
+
+	static CharMatcher from(BitSet chars, String description) {
+		// Compute the filter.
+		long filter = 0;
+		int size = chars.cardinality();
+		boolean containsZero = chars.get(0);
+		// Compute the hash table.
+		char[] table = new char[chooseTableSize(size)];
+		int mask = table.length - 1;
+		for (int c = chars.nextSetBit(0); c != -1; c = chars.nextSetBit(c + 1)) {
+			// Compute the filter at the same time.
+			filter |= 1L << c;
+			int index = smear(c) & mask;
+			while (true) {
+				// Check for empty.
+				if (table[index] == 0) {
+					table[index] = (char) c;
+					break;
+				}
+				// Linear probing.
+				index = (index + 1) & mask;
+			}
+		}
+		return new SmallCharMatcher(table, filter, containsZero, description);
+	}
+
+	@Override
+	public boolean matches(char c) {
+		if (c == 0) {
+			return containsZero;
+		}
+		if (!checkFilter(c)) {
+			return false;
+		}
+		int mask = table.length - 1;
+		int startingIndex = smear(c) & mask;
+		int index = startingIndex;
+		do {
+			// Check for empty.
+			if (table[index] == 0) {
+				return false;
+				// Check for match.
+			} else if (table[index] == c) {
+				return true;
+			} else {
+				// Linear probing.
+				index = (index + 1) & mask;
+			}
+			// Check to see if we wrapped around the whole table.
+		} while (index != startingIndex);
+		return false;
+	}
+
+	@Override
+	void setBits(BitSet table) {
+		if (containsZero) {
+			table.set(0);
+		}
+		for (char c : this.table) {
+			if (c != 0) {
+				table.set(c);
+			}
+		}
+	}
+}

sources/main/java/com/google/common/base/Splitter.java

@@ -0,0 +1,650 @@
+/*
+ * Copyright (C) 2009 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.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import javax.annotation.CheckReturnValue;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+import com.google.common.annotations.GwtIncompatible;
+
+/**
+ * Extracts non-overlapping substrings from an input string, typically by
+ * recognizing appearances of a <i>separator</i> sequence. This separator can be
+ * specified as a single {@linkplain #on(char) character}, fixed
+ * {@linkplain #on(String) string}, {@linkplain #onPattern regular expression}
+ * or {@link #on(CharMatcher) CharMatcher} instance. Or, instead of using a
+ * separator at all, a splitter can extract adjacent substrings of a given
+ * {@linkplain #fixedLength fixed length}.
+ *
+ * <p>
+ * For example, this expression:
+ * 
+ * <pre>
+ *    {@code
+ *
+ *   Splitter.on(',').split("foo,bar,qux")}
+ * </pre>
+ *
+ * ... produces an {@code Iterable} containing {@code "foo"}, {@code "bar"} and
+ * {@code "qux"}, in that order.
+ *
+ * <p>
+ * By default, {@code Splitter}'s behavior is simplistic and unassuming. The
+ * following expression:
+ * 
+ * <pre>
+ *    {@code
+ *
+ *   Splitter.on(',').split(" foo,,,  bar ,")}
+ * </pre>
+ *
+ * ... yields the substrings {@code [" foo", "", "", "  bar ", ""]}. If this is
+ * not the desired behavior, use configuration methods to obtain a <i>new</i>
+ * splitter instance with modified behavior:
+ * 
+ * <pre>
+ * {
+ * 	&#64;code
+ *
+ * 	private static final Splitter MY_SPLITTER = Splitter.on(',').trimResults().omitEmptyStrings();
+ * }
+ * </pre>
+ *
+ * <p>
+ * Now {@code MY_SPLITTER.split("foo,,,  bar ,")} returns just {@code ["foo",
+ * "bar"]}. Note that the order in which these configuration methods are called
+ * is never significant.
+ *
+ * <p>
+ * <b>Warning:</b> Splitter instances are immutable. Invoking a configuration
+ * method has no effect on the receiving instance; you must store and use the
+ * new splitter instance it returns instead.
+ * 
+ * <pre>
+ * {
+ * 	&#64;code
+ *
+ * 	// Do NOT do this
+ * 	Splitter splitter = Splitter.on('/');
+ * 	splitter.trimResults(); // does nothing!
+ * 	return splitter.split("wrong / wrong / wrong");
+ * }
+ * </pre>
+ *
+ * <p>
+ * For separator-based splitters that do not use {@code omitEmptyStrings}, an
+ * input string containing {@code n} occurrences of the separator naturally
+ * yields an iterable of size {@code n + 1}. So if the separator does not occur
+ * anywhere in the input, a single substring is returned containing the entire
+ * input. Consequently, all splitters split the empty string to {@code [""]}
+ * (note: even fixed-length splitters).
+ *
+ * <p>
+ * Splitter instances are thread-safe immutable, and are therefore safe to store
+ * as {@code static final} constants.
+ *
+ * <p>
+ * The {@link Joiner} class provides the inverse operation to splitting, but
+ * note that a round-trip between the two should be assumed to be lossy.
+ *
+ * <p>
+ * See the Guava User Guide article on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/StringsExplained#Splitter">
+ * {@code Splitter}</a>.
+ *
+ * @author Julien Silland
+ * @author Jesse Wilson
+ * @author Kevin Bourrillion
+ * @author Louis Wasserman
+ * @since 1.0
+ */
+@GwtCompatible(emulated = true)
+public final class Splitter {
+	private final CharMatcher trimmer;
+	private final boolean omitEmptyStrings;
+	private final Strategy strategy;
+	private final int limit;
+
+	private Splitter(Strategy strategy) {
+		this(strategy, false, CharMatcher.NONE, Integer.MAX_VALUE);
+	}
+
+	private Splitter(Strategy strategy, boolean omitEmptyStrings, CharMatcher trimmer, int limit) {
+		this.strategy = strategy;
+		this.omitEmptyStrings = omitEmptyStrings;
+		this.trimmer = trimmer;
+		this.limit = limit;
+	}
+
+	/**
+	 * Returns a splitter that uses the given single-character separator. For
+	 * example, {@code Splitter.on(',').split("foo,,bar")} returns an iterable
+	 * containing {@code ["foo", "", "bar"]}.
+	 *
+	 * @param separator the character to recognize as a separator
+	 * @return a splitter, with default settings, that recognizes that separator
+	 */
+	public static Splitter on(char separator) {
+		return on(CharMatcher.is(separator));
+	}
+
+	/**
+	 * Returns a splitter that considers any single character matched by the given
+	 * {@code CharMatcher} to be a separator. For example, {@code
+	 * Splitter.on(CharMatcher.anyOf(";,")).split("foo,;bar,quux")} returns an
+	 * iterable containing {@code ["foo", "", "bar", "quux"]}.
+	 *
+	 * @param separatorMatcher a {@link CharMatcher} that determines whether a
+	 *                         character is a separator
+	 * @return a splitter, with default settings, that uses this matcher
+	 */
+	public static Splitter on(final CharMatcher separatorMatcher) {
+		checkNotNull(separatorMatcher);
+
+		return new Splitter(new Strategy() {
+			@Override
+			public SplittingIterator iterator(Splitter splitter, final CharSequence toSplit) {
+				return new SplittingIterator(splitter, toSplit) {
+					@Override
+					int separatorStart(int start) {
+						return separatorMatcher.indexIn(toSplit, start);
+					}
+
+					@Override
+					int separatorEnd(int separatorPosition) {
+						return separatorPosition + 1;
+					}
+				};
+			}
+		});
+	}
+
+	/**
+	 * Returns a splitter that uses the given fixed string as a separator. For
+	 * example, {@code Splitter.on(", ").split("foo, bar,baz")} returns an iterable
+	 * containing {@code ["foo", "bar,baz"]}.
+	 *
+	 * @param separator the literal, nonempty string to recognize as a separator
+	 * @return a splitter, with default settings, that recognizes that separator
+	 */
+	public static Splitter on(final String separator) {
+		checkArgument(separator.length() != 0, "The separator may not be the empty string.");
+
+		return new Splitter(new Strategy() {
+			@Override
+			public SplittingIterator iterator(Splitter splitter, CharSequence toSplit) {
+				return new SplittingIterator(splitter, toSplit) {
+					@Override
+					public int separatorStart(int start) {
+						int separatorLength = separator.length();
+
+						positions: for (int p = start, last = toSplit.length() - separatorLength; p <= last; p++) {
+							for (int i = 0; i < separatorLength; i++) {
+								if (toSplit.charAt(i + p) != separator.charAt(i)) {
+									continue positions;
+								}
+							}
+							return p;
+						}
+						return -1;
+					}
+
+					@Override
+					public int separatorEnd(int separatorPosition) {
+						return separatorPosition + separator.length();
+					}
+				};
+			}
+		});
+	}
+
+	/**
+	 * Returns a splitter that considers any subsequence matching {@code
+	 * pattern} to be a separator. For example, {@code
+	 * Splitter.on(Pattern.compile("\r?\n")).split(entireFile)} splits a string into
+	 * lines whether it uses DOS-style or UNIX-style line terminators.
+	 *
+	 * @param separatorPattern the pattern that determines whether a subsequence is
+	 *                         a separator. This pattern may not match the empty
+	 *                         string.
+	 * @return a splitter, with default settings, that uses this pattern
+	 * @throws IllegalArgumentException if {@code separatorPattern} matches the
+	 *                                  empty string
+	 */
+	@GwtIncompatible("java.util.regex")
+	public static Splitter on(final Pattern separatorPattern) {
+		checkNotNull(separatorPattern);
+		checkArgument(!separatorPattern.matcher("").matches(), "The pattern may not match the empty string: %s",
+				separatorPattern);
+
+		return new Splitter(new Strategy() {
+			@Override
+			public SplittingIterator iterator(final Splitter splitter, CharSequence toSplit) {
+				final Matcher matcher = separatorPattern.matcher(toSplit);
+				return new SplittingIterator(splitter, toSplit) {
+					@Override
+					public int separatorStart(int start) {
+						return matcher.find(start) ? matcher.start() : -1;
+					}
+
+					@Override
+					public int separatorEnd(int separatorPosition) {
+						return matcher.end();
+					}
+				};
+			}
+		});
+	}
+
+	/**
+	 * Returns a splitter that considers any subsequence matching a given pattern
+	 * (regular expression) to be a separator. For example, {@code
+	 * Splitter.onPattern("\r?\n").split(entireFile)} splits a string into lines
+	 * whether it uses DOS-style or UNIX-style line terminators. This is equivalent
+	 * to {@code Splitter.on(Pattern.compile(pattern))}.
+	 *
+	 * @param separatorPattern the pattern that determines whether a subsequence is
+	 *                         a separator. This pattern may not match the empty
+	 *                         string.
+	 * @return a splitter, with default settings, that uses this pattern
+	 * @throws java.util.regex.PatternSyntaxException if {@code separatorPattern} is
+	 *                                                a malformed expression
+	 * @throws IllegalArgumentException               if {@code separatorPattern}
+	 *                                                matches the empty string
+	 */
+	@GwtIncompatible("java.util.regex")
+	public static Splitter onPattern(String separatorPattern) {
+		return on(Pattern.compile(separatorPattern));
+	}
+
+	/**
+	 * Returns a splitter that divides strings into pieces of the given length. For
+	 * example, {@code Splitter.fixedLength(2).split("abcde")} returns an iterable
+	 * containing {@code ["ab", "cd", "e"]}. The last piece can be smaller than
+	 * {@code length} but will never be empty.
+	 *
+	 * <p>
+	 * <b>Exception:</b> for consistency with separator-based splitters, {@code
+	 * split("")} does not yield an empty iterable, but an iterable containing
+	 * {@code ""}. This is the only case in which {@code
+	 * Iterables.size(split(input))} does not equal {@code
+	 * IntMath.divide(input.length(), length, CEILING)}. To avoid this behavior, use
+	 * {@code omitEmptyStrings}.
+	 *
+	 * @param length the desired length of pieces after splitting, a positive
+	 *               integer
+	 * @return a splitter, with default settings, that can split into fixed sized
+	 *         pieces
+	 * @throws IllegalArgumentException if {@code length} is zero or negative
+	 */
+	public static Splitter fixedLength(final int length) {
+		checkArgument(length > 0, "The length may not be less than 1");
+
+		return new Splitter(new Strategy() {
+			@Override
+			public SplittingIterator iterator(final Splitter splitter, CharSequence toSplit) {
+				return new SplittingIterator(splitter, toSplit) {
+					@Override
+					public int separatorStart(int start) {
+						int nextChunkStart = start + length;
+						return (nextChunkStart < toSplit.length() ? nextChunkStart : -1);
+					}
+
+					@Override
+					public int separatorEnd(int separatorPosition) {
+						return separatorPosition;
+					}
+				};
+			}
+		});
+	}
+
+	/**
+	 * Returns a splitter that behaves equivalently to {@code this} splitter, but
+	 * automatically omits empty strings from the results. For example, {@code
+	 * Splitter.on(',').omitEmptyStrings().split(",a,,,b,c,,")} returns an iterable
+	 * containing only {@code ["a", "b", "c"]}.
+	 *
+	 * <p>
+	 * If either {@code trimResults} option is also specified when creating a
+	 * splitter, that splitter always trims results first before checking for
+	 * emptiness. So, for example, {@code
+	 * Splitter.on(':').omitEmptyStrings().trimResults().split(": : : ")} returns an
+	 * empty iterable.
+	 *
+	 * <p>
+	 * Note that it is ordinarily not possible for {@link #split(CharSequence)} to
+	 * return an empty iterable, but when using this option, it can (if the input
+	 * sequence consists of nothing but separators).
+	 *
+	 * @return a splitter with the desired configuration
+	 */
+	@CheckReturnValue
+	public Splitter omitEmptyStrings() {
+		return new Splitter(strategy, true, trimmer, limit);
+	}
+
+	/**
+	 * Returns a splitter that behaves equivalently to {@code this} splitter but
+	 * stops splitting after it reaches the limit. The limit defines the maximum
+	 * number of items returned by the iterator.
+	 *
+	 * <p>
+	 * For example, {@code Splitter.on(',').limit(3).split("a,b,c,d")} returns an
+	 * iterable containing {@code ["a", "b", "c,d"]}. When omitting empty strings,
+	 * the omitted strings do no count. Hence,
+	 * {@code Splitter.on(',').limit(3).omitEmptyStrings().split("a,,,b,,,c,d")}
+	 * returns an iterable containing {@code ["a", "b", "c,d"}. When trim is
+	 * requested, all entries, including the last are trimmed. Hence
+	 * {@code Splitter.on(',').limit(3).trimResults().split(" a , b , c , d ")}
+	 * results in @{code ["a", "b", "c , d"]}.
+	 *
+	 * @param limit the maximum number of items returns
+	 * @return a splitter with the desired configuration
+	 * @since 9.0
+	 */
+	@CheckReturnValue
+	public Splitter limit(int limit) {
+		checkArgument(limit > 0, "must be greater than zero: %s", limit);
+		return new Splitter(strategy, omitEmptyStrings, trimmer, limit);
+	}
+
+	/**
+	 * Returns a splitter that behaves equivalently to {@code this} splitter, but
+	 * automatically removes leading and trailing {@linkplain CharMatcher#WHITESPACE
+	 * whitespace} from each returned substring; equivalent to
+	 * {@code trimResults(CharMatcher.WHITESPACE)}. For example, {@code
+	 * Splitter.on(',').trimResults().split(" a, b ,c ")} returns an iterable
+	 * containing {@code ["a", "b", "c"]}.
+	 *
+	 * @return a splitter with the desired configuration
+	 */
+	@CheckReturnValue
+	public Splitter trimResults() {
+		return trimResults(CharMatcher.WHITESPACE);
+	}
+
+	/**
+	 * Returns a splitter that behaves equivalently to {@code this} splitter, but
+	 * removes all leading or trailing characters matching the given {@code
+	 * CharMatcher} from each returned substring. For example, {@code
+	 * Splitter.on(',').trimResults(CharMatcher.is('_')).split("_a ,_b_ ,c__")}
+	 * returns an iterable containing {@code ["a ", "b_ ", "c"]}.
+	 *
+	 * @param trimmer a {@link CharMatcher} that determines whether a character
+	 *                should be removed from the beginning/end of a subsequence
+	 * @return a splitter with the desired configuration
+	 */
+	// TODO(kevinb): throw if a trimmer was already specified!
+	@CheckReturnValue
+	public Splitter trimResults(CharMatcher trimmer) {
+		checkNotNull(trimmer);
+		return new Splitter(strategy, omitEmptyStrings, trimmer, limit);
+	}
+
+	/**
+	 * Splits {@code sequence} into string components and makes them available
+	 * through an {@link Iterator}, which may be lazily evaluated. If you want an
+	 * eagerly computed {@link List}, use {@link #splitToList(CharSequence)}.
+	 *
+	 * @param sequence the sequence of characters to split
+	 * @return an iteration over the segments split from the parameter.
+	 */
+	public Iterable<String> split(final CharSequence sequence) {
+		checkNotNull(sequence);
+
+		return new Iterable<String>() {
+			@Override
+			public Iterator<String> iterator() {
+				return splittingIterator(sequence);
+			}
+
+			@Override
+			public String toString() {
+				return Joiner.on(", ").appendTo(new StringBuilder().append('['), this).append(']').toString();
+			}
+		};
+	}
+
+	private Iterator<String> splittingIterator(CharSequence sequence) {
+		return strategy.iterator(this, sequence);
+	}
+
+	/**
+	 * Splits {@code sequence} into string components and returns them as an
+	 * immutable list. If you want an {@link Iterable} which may be lazily
+	 * evaluated, use {@link #split(CharSequence)}.
+	 *
+	 * @param sequence the sequence of characters to split
+	 * @return an immutable list of the segments split from the parameter
+	 * @since 15.0
+	 */
+	@Beta
+	public List<String> splitToList(CharSequence sequence) {
+		checkNotNull(sequence);
+
+		Iterator<String> iterator = splittingIterator(sequence);
+		List<String> result = new ArrayList<String>();
+
+		while (iterator.hasNext()) {
+			result.add(iterator.next());
+		}
+
+		return Collections.unmodifiableList(result);
+	}
+
+	/**
+	 * Returns a {@code MapSplitter} which splits entries based on this splitter,
+	 * and splits entries into keys and values using the specified separator.
+	 *
+	 * @since 10.0
+	 */
+	@CheckReturnValue
+	@Beta
+	public MapSplitter withKeyValueSeparator(String separator) {
+		return withKeyValueSeparator(on(separator));
+	}
+
+	/**
+	 * Returns a {@code MapSplitter} which splits entries based on this splitter,
+	 * and splits entries into keys and values using the specified separator.
+	 *
+	 * @since 14.0
+	 */
+	@CheckReturnValue
+	@Beta
+	public MapSplitter withKeyValueSeparator(char separator) {
+		return withKeyValueSeparator(on(separator));
+	}
+
+	/**
+	 * Returns a {@code MapSplitter} which splits entries based on this splitter,
+	 * and splits entries into keys and values using the specified key-value
+	 * splitter.
+	 *
+	 * @since 10.0
+	 */
+	@CheckReturnValue
+	@Beta
+	public MapSplitter withKeyValueSeparator(Splitter keyValueSplitter) {
+		return new MapSplitter(this, keyValueSplitter);
+	}
+
+	/**
+	 * An object that splits strings into maps as {@code Splitter} splits iterables
+	 * and lists. Like {@code Splitter}, it is thread-safe and immutable.
+	 *
+	 * @since 10.0
+	 */
+	@Beta
+	public static final class MapSplitter {
+		private static final String INVALID_ENTRY_MESSAGE = "Chunk [%s] is not a valid entry";
+		private final Splitter outerSplitter;
+		private final Splitter entrySplitter;
+
+		private MapSplitter(Splitter outerSplitter, Splitter entrySplitter) {
+			this.outerSplitter = outerSplitter; // only "this" is passed
+			this.entrySplitter = checkNotNull(entrySplitter);
+		}
+
+		/**
+		 * Splits {@code sequence} into substrings, splits each substring into an entry,
+		 * and returns an unmodifiable map with each of the entries. For example, <code>
+		 * Splitter.on(';').trimResults().withKeyValueSeparator("=>")
+		 * .split("a=>b ; c=>b")
+		 * </code> will return a mapping from {@code "a"} to {@code "b"} and {@code "c"}
+		 * to {@code b}.
+		 *
+		 * <p>
+		 * The returned map preserves the order of the entries from {@code sequence}.
+		 *
+		 * @throws IllegalArgumentException if the specified sequence does not split
+		 *                                  into valid map entries, or if there are
+		 *                                  duplicate keys
+		 */
+		public Map<String, String> split(CharSequence sequence) {
+			Map<String, String> map = new LinkedHashMap<String, String>();
+			for (String entry : outerSplitter.split(sequence)) {
+				Iterator<String> entryFields = entrySplitter.splittingIterator(entry);
+
+				checkArgument(entryFields.hasNext(), INVALID_ENTRY_MESSAGE, entry);
+				String key = entryFields.next();
+				checkArgument(!map.containsKey(key), "Duplicate key [%s] found.", key);
+
+				checkArgument(entryFields.hasNext(), INVALID_ENTRY_MESSAGE, entry);
+				String value = entryFields.next();
+				map.put(key, value);
+
+				checkArgument(!entryFields.hasNext(), INVALID_ENTRY_MESSAGE, entry);
+			}
+			return Collections.unmodifiableMap(map);
+		}
+	}
+
+	private interface Strategy {
+		Iterator<String> iterator(Splitter splitter, CharSequence toSplit);
+	}
+
+	private abstract static class SplittingIterator extends AbstractIterator<String> {
+		final CharSequence toSplit;
+		final CharMatcher trimmer;
+		final boolean omitEmptyStrings;
+
+		/**
+		 * Returns the first index in {@code toSplit} at or after {@code start} that
+		 * contains the separator.
+		 */
+		abstract int separatorStart(int start);
+
+		/**
+		 * Returns the first index in {@code toSplit} after {@code
+		 * separatorPosition} that does not contain a separator. This method is only
+		 * invoked after a call to {@code separatorStart}.
+		 */
+		abstract int separatorEnd(int separatorPosition);
+
+		int offset = 0;
+		int limit;
+
+		protected SplittingIterator(Splitter splitter, CharSequence toSplit) {
+			this.trimmer = splitter.trimmer;
+			this.omitEmptyStrings = splitter.omitEmptyStrings;
+			this.limit = splitter.limit;
+			this.toSplit = toSplit;
+		}
+
+		@Override
+		protected String computeNext() {
+			/*
+			 * The returned string will be from the end of the last match to the beginning
+			 * of the next one. nextStart is the start position of the returned substring,
+			 * while offset is the place to start looking for a separator.
+			 */
+			int nextStart = offset;
+			while (offset != -1) {
+				int start = nextStart;
+				int end;
+
+				int separatorPosition = separatorStart(offset);
+				if (separatorPosition == -1) {
+					end = toSplit.length();
+					offset = -1;
+				} else {
+					end = separatorPosition;
+					offset = separatorEnd(separatorPosition);
+				}
+				if (offset == nextStart) {
+					/*
+					 * This occurs when some pattern has an empty match, even if it doesn't match
+					 * the empty string -- for example, if it requires lookahead or the like. The
+					 * offset must be increased to look for separators beyond this point, without
+					 * changing the start position of the next returned substring -- so nextStart
+					 * stays the same.
+					 */
+					offset++;
+					if (offset >= toSplit.length()) {
+						offset = -1;
+					}
+					continue;
+				}
+
+				while (start < end && trimmer.matches(toSplit.charAt(start))) {
+					start++;
+				}
+				while (end > start && trimmer.matches(toSplit.charAt(end - 1))) {
+					end--;
+				}
+
+				if (omitEmptyStrings && start == end) {
+					// Don't include the (unused) separator in next split string.
+					nextStart = offset;
+					continue;
+				}
+
+				if (limit == 1) {
+					// The limit has been reached, return the rest of the string as the
+					// final item. This is tested after empty string removal so that
+					// empty strings do not count towards the limit.
+					end = toSplit.length();
+					offset = -1;
+					// Since we may have changed the end, we need to trim it again.
+					while (end > start && trimmer.matches(toSplit.charAt(end - 1))) {
+						end--;
+					}
+				} else {
+					limit--;
+				}
+
+				return toSplit.subSequence(start, end).toString();
+			}
+			return endOfData();
+		}
+	}
+}

sources/main/java/com/google/common/base/StandardSystemProperty.java

@@ -0,0 +1,144 @@
+/*
+ * Copyright (C) 2012 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 com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtIncompatible;
+
+/**
+ * Represents a {@linkplain System#getProperties() standard system property}.
+ *
+ * @author Kurt Alfred Kluever
+ * @since 15.0
+ */
+@Beta
+@GwtIncompatible("java.lang.System#getProperty")
+public enum StandardSystemProperty {
+
+	/** Java Runtime Environment version. */
+	JAVA_VERSION("java.version"),
+
+	/** Java Runtime Environment vendor. */
+	JAVA_VENDOR("java.vendor"),
+
+	/** Java vendor URL. */
+	JAVA_VENDOR_URL("java.vendor.url"),
+
+	/** Java installation directory. */
+	JAVA_HOME("java.home"),
+
+	/** Java Virtual Machine specification version. */
+	JAVA_VM_SPECIFICATION_VERSION("java.vm.specification.version"),
+
+	/** Java Virtual Machine specification vendor. */
+	JAVA_VM_SPECIFICATION_VENDOR("java.vm.specification.vendor"),
+
+	/** Java Virtual Machine specification name. */
+	JAVA_VM_SPECIFICATION_NAME("java.vm.specification.name"),
+
+	/** Java Virtual Machine implementation version. */
+	JAVA_VM_VERSION("java.vm.version"),
+
+	/** Java Virtual Machine implementation vendor. */
+	JAVA_VM_VENDOR("java.vm.vendor"),
+
+	/** Java Virtual Machine implementation name. */
+	JAVA_VM_NAME("java.vm.name"),
+
+	/** Java Runtime Environment specification version. */
+	JAVA_SPECIFICATION_VERSION("java.specification.version"),
+
+	/** Java Runtime Environment specification vendor. */
+	JAVA_SPECIFICATION_VENDOR("java.specification.vendor"),
+
+	/** Java Runtime Environment specification name. */
+	JAVA_SPECIFICATION_NAME("java.specification.name"),
+
+	/** Java class format version number. */
+	JAVA_CLASS_VERSION("java.class.version"),
+
+	/** Java class path. */
+	JAVA_CLASS_PATH("java.class.path"),
+
+	/** List of paths to search when loading libraries. */
+	JAVA_LIBRARY_PATH("java.library.path"),
+
+	/** Default temp file path. */
+	JAVA_IO_TMPDIR("java.io.tmpdir"),
+
+	/** Name of JIT compiler to use. */
+	JAVA_COMPILER("java.compiler"),
+
+	/** Path of extension directory or directories. */
+	JAVA_EXT_DIRS("java.ext.dirs"),
+
+	/** Operating system name. */
+	OS_NAME("os.name"),
+
+	/** Operating system architecture. */
+	OS_ARCH("os.arch"),
+
+	/** Operating system version. */
+	OS_VERSION("os.version"),
+
+	/** File separator ("/" on UNIX). */
+	FILE_SEPARATOR("file.separator"),
+
+	/** Path separator (":" on UNIX). */
+	PATH_SEPARATOR("path.separator"),
+
+	/** Line separator ("\n" on UNIX). */
+	LINE_SEPARATOR("line.separator"),
+
+	/** User's account name. */
+	USER_NAME("user.name"),
+
+	/** User's home directory. */
+	USER_HOME("user.home"),
+
+	/** User's current working directory. */
+	USER_DIR("user.dir");
+
+	private final String key;
+
+	private StandardSystemProperty(String key) {
+		this.key = key;
+	}
+
+	/**
+	 * Returns the key used to lookup this system property.
+	 */
+	public String key() {
+		return key;
+	}
+
+	/**
+	 * Returns the current value for this system property by delegating to
+	 * {@link System#getProperty(String)}.
+	 */
+	public String value() {
+		return System.getProperty(key);
+	}
+
+	/**
+	 * Returns a string representation of this system property.
+	 */
+	@Override
+	public String toString() {
+		return key() + "=" + value();
+	}
+}

sources/main/java/com/google/common/base/Strings.java

@@ -0,0 +1,240 @@
+/*
+ * Copyright (C) 2010 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.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import java.util.Formatter;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.GwtCompatible;
+import com.google.common.annotations.VisibleForTesting;
+
+/**
+ * Static utility methods pertaining to {@code String} or {@code CharSequence}
+ * instances.
+ *
+ * @author Kevin Bourrillion
+ * @since 3.0
+ */
+@GwtCompatible
+public final class Strings {
+	private Strings() {
+	}
+
+	/**
+	 * Returns the given string if it is non-null; the empty string otherwise.
+	 *
+	 * @param string the string to test and possibly return
+	 * @return {@code string} itself if it is non-null; {@code ""} if it is null
+	 */
+	public static String nullToEmpty(@Nullable String string) {
+		return (string == null) ? "" : string;
+	}
+
+	/**
+	 * Returns the given string if it is nonempty; {@code null} otherwise.
+	 *
+	 * @param string the string to test and possibly return
+	 * @return {@code string} itself if it is nonempty; {@code null} if it is empty
+	 *         or null
+	 */
+	public static @Nullable String emptyToNull(@Nullable String string) {
+		return isNullOrEmpty(string) ? null : string;
+	}
+
+	/**
+	 * Returns {@code true} if the given string is null or is the empty string.
+	 *
+	 * <p>
+	 * Consider normalizing your string references with {@link #nullToEmpty}. If you
+	 * do, you can use {@link String#isEmpty()} instead of this method, and you
+	 * won't need special null-safe forms of methods like {@link String#toUpperCase}
+	 * either. Or, if you'd like to normalize "in the other direction," converting
+	 * empty strings to {@code null}, you can use {@link #emptyToNull}.
+	 *
+	 * @param string a string reference to check
+	 * @return {@code true} if the string is null or is the empty string
+	 */
+	public static boolean isNullOrEmpty(@Nullable String string) {
+		return string == null || string.length() == 0; // string.isEmpty() in Java 6
+	}
+
+	/**
+	 * Returns a string, of length at least {@code minLength}, consisting of
+	 * {@code string} prepended with as many copies of {@code padChar} as are
+	 * necessary to reach that length. For example,
+	 *
+	 * <ul>
+	 * <li>{@code padStart("7", 3, '0')} returns {@code "007"}
+	 * <li>{@code padStart("2010", 3, '0')} returns {@code "2010"}
+	 * </ul>
+	 *
+	 * <p>
+	 * See {@link Formatter} for a richer set of formatting capabilities.
+	 *
+	 * @param string    the string which should appear at the end of the result
+	 * @param minLength the minimum length the resulting string must have. Can be
+	 *                  zero or negative, in which case the input string is always
+	 *                  returned.
+	 * @param padChar   the character to insert at the beginning of the result until
+	 *                  the minimum length is reached
+	 * @return the padded string
+	 */
+	public static String padStart(String string, int minLength, char padChar) {
+		checkNotNull(string); // eager for GWT.
+		if (string.length() >= minLength) {
+			return string;
+		}
+		StringBuilder sb = new StringBuilder(minLength);
+		for (int i = string.length(); i < minLength; i++) {
+			sb.append(padChar);
+		}
+		sb.append(string);
+		return sb.toString();
+	}
+
+	/**
+	 * Returns a string, of length at least {@code minLength}, consisting of
+	 * {@code string} appended with as many copies of {@code padChar} as are
+	 * necessary to reach that length. For example,
+	 *
+	 * <ul>
+	 * <li>{@code padEnd("4.", 5, '0')} returns {@code "4.000"}
+	 * <li>{@code padEnd("2010", 3, '!')} returns {@code "2010"}
+	 * </ul>
+	 *
+	 * <p>
+	 * See {@link Formatter} for a richer set of formatting capabilities.
+	 *
+	 * @param string    the string which should appear at the beginning of the
+	 *                  result
+	 * @param minLength the minimum length the resulting string must have. Can be
+	 *                  zero or negative, in which case the input string is always
+	 *                  returned.
+	 * @param padChar   the character to append to the end of the result until the
+	 *                  minimum length is reached
+	 * @return the padded string
+	 */
+	public static String padEnd(String string, int minLength, char padChar) {
+		checkNotNull(string); // eager for GWT.
+		if (string.length() >= minLength) {
+			return string;
+		}
+		StringBuilder sb = new StringBuilder(minLength);
+		sb.append(string);
+		for (int i = string.length(); i < minLength; i++) {
+			sb.append(padChar);
+		}
+		return sb.toString();
+	}
+
+	/**
+	 * Returns a string consisting of a specific number of concatenated copies of an
+	 * input string. For example, {@code repeat("hey", 3)} returns the string
+	 * {@code "heyheyhey"}.
+	 *
+	 * @param string any non-null string
+	 * @param count  the number of times to repeat it; a nonnegative integer
+	 * @return a string containing {@code string} repeated {@code count} times (the
+	 *         empty string if {@code count} is zero)
+	 * @throws IllegalArgumentException if {@code count} is negative
+	 */
+	public static String repeat(String string, int count) {
+		checkNotNull(string); // eager for GWT.
+
+		if (count <= 1) {
+			checkArgument(count >= 0, "invalid count: %s", count);
+			return (count == 0) ? "" : string;
+		}
+
+		// IF YOU MODIFY THE CODE HERE, you must update StringsRepeatBenchmark
+		final int len = string.length();
+		final long longSize = (long) len * (long) count;
+		final int size = (int) longSize;
+		if (size != longSize) {
+			throw new ArrayIndexOutOfBoundsException("Required array size too large: " + longSize);
+		}
+
+		final char[] array = new char[size];
+		string.getChars(0, len, array, 0);
+		int n;
+		for (n = len; n < size - n; n <<= 1) {
+			System.arraycopy(array, 0, array, n, n);
+		}
+		System.arraycopy(array, 0, array, n, size - n);
+		return new String(array);
+	}
+
+	/**
+	 * Returns the longest string {@code prefix} such that
+	 * {@code a.toString().startsWith(prefix) && b.toString().startsWith(prefix)},
+	 * taking care not to split surrogate pairs. If {@code a} and {@code b} have no
+	 * common prefix, returns the empty string.
+	 *
+	 * @since 11.0
+	 */
+	public static String commonPrefix(CharSequence a, CharSequence b) {
+		checkNotNull(a);
+		checkNotNull(b);
+
+		int maxPrefixLength = Math.min(a.length(), b.length());
+		int p = 0;
+		while (p < maxPrefixLength && a.charAt(p) == b.charAt(p)) {
+			p++;
+		}
+		if (validSurrogatePairAt(a, p - 1) || validSurrogatePairAt(b, p - 1)) {
+			p--;
+		}
+		return a.subSequence(0, p).toString();
+	}
+
+	/**
+	 * Returns the longest string {@code suffix} such that
+	 * {@code a.toString().endsWith(suffix) && b.toString().endsWith(suffix)},
+	 * taking care not to split surrogate pairs. If {@code a} and {@code b} have no
+	 * common suffix, returns the empty string.
+	 *
+	 * @since 11.0
+	 */
+	public static String commonSuffix(CharSequence a, CharSequence b) {
+		checkNotNull(a);
+		checkNotNull(b);
+
+		int maxSuffixLength = Math.min(a.length(), b.length());
+		int s = 0;
+		while (s < maxSuffixLength && a.charAt(a.length() - s - 1) == b.charAt(b.length() - s - 1)) {
+			s++;
+		}
+		if (validSurrogatePairAt(a, a.length() - s - 1) || validSurrogatePairAt(b, b.length() - s - 1)) {
+			s--;
+		}
+		return a.subSequence(a.length() - s, a.length()).toString();
+	}
+
+	/**
+	 * True when a valid surrogate pair starts at the given {@code index} in the
+	 * given {@code string}. Out-of-range indexes return false.
+	 */
+	@VisibleForTesting
+	static boolean validSurrogatePairAt(CharSequence string, int index) {
+		return index >= 0 && index <= (string.length() - 2) && Character.isHighSurrogate(string.charAt(index))
+				&& Character.isLowSurrogate(string.charAt(index + 1));
+	}
+}

sources/main/java/com/google/common/base/Supplier.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2007 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 com.google.common.annotations.GwtCompatible;
+
+/**
+ * A class that can supply objects of a single type. Semantically, this could be
+ * a factory, generator, builder, closure, or something else entirely. No
+ * guarantees are implied by this interface.
+ *
+ * @author Harry Heymann
+ * @since 2.0 (imported from Google Collections Library)
+ */
+@GwtCompatible
+public interface Supplier<T> {
+	/**
+	 * Retrieves an instance of the appropriate type. The returned object may or may
+	 * not be a new instance, depending on the implementation.
+	 *
+	 * @return an instance of the appropriate type
+	 */
+	T get();
+}

sources/main/java/com/google/common/base/Suppliers.java

@@ -0,0 +1,322 @@
+/*
+ * Copyright (C) 2007 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 java.io.Serializable;
+import java.util.concurrent.TimeUnit;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+import com.google.common.annotations.VisibleForTesting;
+
+/**
+ * Useful suppliers.
+ *
+ * <p>
+ * All methods return serializable suppliers as long as they're given
+ * serializable parameters.
+ *
+ * @author Laurence Gonsalves
+ * @author Harry Heymann
+ * @since 2.0 (imported from Google Collections Library)
+ */
+@GwtCompatible
+public final class Suppliers {
+	private Suppliers() {
+	}
+
+	/**
+	 * Returns a new supplier which is the composition of the provided function and
+	 * supplier. In other words, the new supplier's value will be computed by
+	 * retrieving the value from {@code supplier}, and then applying
+	 * {@code function} to that value. Note that the resulting supplier will not
+	 * call {@code supplier} or invoke {@code function} until it is called.
+	 */
+	public static <F, T> Supplier<T> compose(Function<? super F, T> function, Supplier<F> supplier) {
+		Preconditions.checkNotNull(function);
+		Preconditions.checkNotNull(supplier);
+		return new SupplierComposition<F, T>(function, supplier);
+	}
+
+	private static class SupplierComposition<F, T> implements Supplier<T>, Serializable {
+		final Function<? super F, T> function;
+		final Supplier<F> supplier;
+
+		SupplierComposition(Function<? super F, T> function, Supplier<F> supplier) {
+			this.function = function;
+			this.supplier = supplier;
+		}
+
+		@Override
+		public T get() {
+			return function.apply(supplier.get());
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof SupplierComposition) {
+				SupplierComposition<?, ?> that = (SupplierComposition<?, ?>) obj;
+				return function.equals(that.function) && supplier.equals(that.supplier);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return Objects.hashCode(function, supplier);
+		}
+
+		@Override
+		public String toString() {
+			return "Suppliers.compose(" + function + ", " + supplier + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns a supplier which caches the instance retrieved during the first call
+	 * to {@code get()} and returns that value on subsequent calls to {@code get()}.
+	 * See: <a href="http://en.wikipedia.org/wiki/Memoization">memoization</a>
+	 *
+	 * <p>
+	 * The returned supplier is thread-safe. The supplier's serialized form does not
+	 * contain the cached value, which will be recalculated when {@code
+	 * get()} is called on the reserialized instance.
+	 *
+	 * <p>
+	 * If {@code delegate} is an instance created by an earlier call to {@code
+	 * memoize}, it is returned directly.
+	 */
+	public static <T> Supplier<T> memoize(Supplier<T> delegate) {
+		return (delegate instanceof MemoizingSupplier) ? delegate
+				: new MemoizingSupplier<T>(Preconditions.checkNotNull(delegate));
+	}
+
+	@VisibleForTesting
+	static class MemoizingSupplier<T> implements Supplier<T>, Serializable {
+		final Supplier<T> delegate;
+		transient volatile boolean initialized;
+		// "value" does not need to be volatile; visibility piggy-backs
+		// on volatile read of "initialized".
+		transient T value;
+
+		MemoizingSupplier(Supplier<T> delegate) {
+			this.delegate = delegate;
+		}
+
+		@Override
+		public T get() {
+			// A 2-field variant of Double Checked Locking.
+			if (!initialized) {
+				synchronized (this) {
+					if (!initialized) {
+						T t = delegate.get();
+						value = t;
+						initialized = true;
+						return t;
+					}
+				}
+			}
+			return value;
+		}
+
+		@Override
+		public String toString() {
+			return "Suppliers.memoize(" + delegate + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns a supplier that caches the instance supplied by the delegate and
+	 * removes the cached value after the specified time has passed. Subsequent
+	 * calls to {@code get()} return the cached value if the expiration time has not
+	 * passed. After the expiration time, a new value is retrieved, cached, and
+	 * returned. See:
+	 * <a href="http://en.wikipedia.org/wiki/Memoization">memoization</a>
+	 *
+	 * <p>
+	 * The returned supplier is thread-safe. The supplier's serialized form does not
+	 * contain the cached value, which will be recalculated when {@code
+	 * get()} is called on the reserialized instance.
+	 *
+	 * @param duration the length of time after a value is created that it should
+	 *                 stop being returned by subsequent {@code get()} calls
+	 * @param unit     the unit that {@code duration} is expressed in
+	 * @throws IllegalArgumentException if {@code duration} is not positive
+	 * @since 2.0
+	 */
+	public static <T> Supplier<T> memoizeWithExpiration(Supplier<T> delegate, long duration, TimeUnit unit) {
+		return new ExpiringMemoizingSupplier<T>(delegate, duration, unit);
+	}
+
+	@VisibleForTesting
+	static class ExpiringMemoizingSupplier<T> implements Supplier<T>, Serializable {
+		final Supplier<T> delegate;
+		final long durationNanos;
+		transient volatile T value;
+		// The special value 0 means "not yet initialized".
+		transient volatile long expirationNanos;
+
+		ExpiringMemoizingSupplier(Supplier<T> delegate, long duration, TimeUnit unit) {
+			this.delegate = Preconditions.checkNotNull(delegate);
+			this.durationNanos = unit.toNanos(duration);
+			Preconditions.checkArgument(duration > 0);
+		}
+
+		@Override
+		public T get() {
+			// Another variant of Double Checked Locking.
+			//
+			// We use two volatile reads. We could reduce this to one by
+			// putting our fields into a holder class, but (at least on x86)
+			// the extra memory consumption and indirection are more
+			// expensive than the extra volatile reads.
+			long nanos = expirationNanos;
+			long now = Platform.systemNanoTime();
+			if (nanos == 0 || now - nanos >= 0) {
+				synchronized (this) {
+					if (nanos == expirationNanos) { // recheck for lost race
+						T t = delegate.get();
+						value = t;
+						nanos = now + durationNanos;
+						// In the very unlikely event that nanos is 0, set it to 1;
+						// no one will notice 1 ns of tardiness.
+						expirationNanos = (nanos == 0) ? 1 : nanos;
+						return t;
+					}
+				}
+			}
+			return value;
+		}
+
+		@Override
+		public String toString() {
+			// This is a little strange if the unit the user provided was not NANOS,
+			// but we don't want to store the unit just for toString
+			return "Suppliers.memoizeWithExpiration(" + delegate + ", " + durationNanos + ", NANOS)";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns a supplier that always supplies {@code instance}.
+	 */
+	public static <T> Supplier<T> ofInstance(@Nullable T instance) {
+		return new SupplierOfInstance<T>(instance);
+	}
+
+	private static class SupplierOfInstance<T> implements Supplier<T>, Serializable {
+		final T instance;
+
+		SupplierOfInstance(@Nullable T instance) {
+			this.instance = instance;
+		}
+
+		@Override
+		public T get() {
+			return instance;
+		}
+
+		@Override
+		public boolean equals(@Nullable Object obj) {
+			if (obj instanceof SupplierOfInstance) {
+				SupplierOfInstance<?> that = (SupplierOfInstance<?>) obj;
+				return Objects.equal(instance, that.instance);
+			}
+			return false;
+		}
+
+		@Override
+		public int hashCode() {
+			return Objects.hashCode(instance);
+		}
+
+		@Override
+		public String toString() {
+			return "Suppliers.ofInstance(" + instance + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns a supplier whose {@code get()} method synchronizes on
+	 * {@code delegate} before calling it, making it thread-safe.
+	 */
+	public static <T> Supplier<T> synchronizedSupplier(Supplier<T> delegate) {
+		return new ThreadSafeSupplier<T>(Preconditions.checkNotNull(delegate));
+	}
+
+	private static class ThreadSafeSupplier<T> implements Supplier<T>, Serializable {
+		final Supplier<T> delegate;
+
+		ThreadSafeSupplier(Supplier<T> delegate) {
+			this.delegate = delegate;
+		}
+
+		@Override
+		public T get() {
+			synchronized (delegate) {
+				return delegate.get();
+			}
+		}
+
+		@Override
+		public String toString() {
+			return "Suppliers.synchronizedSupplier(" + delegate + ")";
+		}
+
+		private static final long serialVersionUID = 0;
+	}
+
+	/**
+	 * Returns a function that accepts a supplier and returns the result of invoking
+	 * {@link Supplier#get} on that supplier.
+	 *
+	 * @since 8.0
+	 */
+	@Beta
+	public static <T> Function<Supplier<T>, T> supplierFunction() {
+		@SuppressWarnings("unchecked") // implementation is "fully variant"
+		SupplierFunction<T> sf = (SupplierFunction<T>) SupplierFunctionImpl.INSTANCE;
+		return sf;
+	}
+
+	private interface SupplierFunction<T> extends Function<Supplier<T>, T> {
+	}
+
+	private enum SupplierFunctionImpl implements SupplierFunction<Object> {
+		INSTANCE;
+
+		// Note: This makes T a "pass-through type"
+		@Override
+		public Object apply(Supplier<Object> input) {
+			return input.get();
+		}
+
+		@Override
+		public String toString() {
+			return "Suppliers.supplierFunction()";
+		}
+	}
+}

sources/main/java/com/google/common/base/Throwables.java

@@ -0,0 +1,226 @@
+/*
+ * Copyright (C) 2007 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.PrintWriter;
+import java.io.StringWriter;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+
+import net.lax1dude.eaglercraft.v1_8.EagRuntime;
+
+/**
+ * Static utility methods pertaining to instances of {@link Throwable}.
+ *
+ * <p>
+ * See the Guava User Guide entry on
+ * <a href= "http://code.google.com/p/guava-libraries/wiki/ThrowablesExplained">
+ * Throwables</a>.
+ *
+ * @author Kevin Bourrillion
+ * @author Ben Yu
+ * @since 1.0
+ */
+public final class Throwables {
+	private Throwables() {
+	}
+
+	/**
+	 * Propagates {@code throwable} exactly as-is, if and only if it is an instance
+	 * of {@code declaredType}. Example usage:
+	 * 
+	 * <pre>
+	 * try {
+	 * 	someMethodThatCouldThrowAnything();
+	 * } catch (IKnowWhatToDoWithThisException e) {
+	 * 	handle(e);
+	 * } catch (Throwable t) {
+	 * 	Throwables.propagateIfInstanceOf(t, IOException.class);
+	 * 	Throwables.propagateIfInstanceOf(t, SQLException.class);
+	 * 	throw Throwables.propagate(t);
+	 * }
+	 * </pre>
+	 */
+	public static <X extends Throwable> void propagateIfInstanceOf(@Nullable Throwable throwable, Class<X> declaredType)
+			throws X {
+		// Check for null is needed to avoid frequent JNI calls to isInstance().
+		if (throwable != null && declaredType.isInstance(throwable)) {
+			throw declaredType.cast(throwable);
+		}
+	}
+
+	/**
+	 * Propagates {@code throwable} exactly as-is, if and only if it is an instance
+	 * of {@link RuntimeException} or {@link Error}. Example usage:
+	 * 
+	 * <pre>
+	 * try {
+	 * 	someMethodThatCouldThrowAnything();
+	 * } catch (IKnowWhatToDoWithThisException e) {
+	 * 	handle(e);
+	 * } catch (Throwable t) {
+	 * 	Throwables.propagateIfPossible(t);
+	 * 	throw new RuntimeException("unexpected", t);
+	 * }
+	 * </pre>
+	 */
+	public static void propagateIfPossible(@Nullable Throwable throwable) {
+		propagateIfInstanceOf(throwable, Error.class);
+		propagateIfInstanceOf(throwable, RuntimeException.class);
+	}
+
+	/**
+	 * Propagates {@code throwable} exactly as-is, if and only if it is an instance
+	 * of {@link RuntimeException}, {@link Error}, or {@code declaredType}. Example
+	 * usage:
+	 * 
+	 * <pre>
+	 * try {
+	 * 	someMethodThatCouldThrowAnything();
+	 * } catch (IKnowWhatToDoWithThisException e) {
+	 * 	handle(e);
+	 * } catch (Throwable t) {
+	 * 	Throwables.propagateIfPossible(t, OtherException.class);
+	 * 	throw new RuntimeException("unexpected", t);
+	 * }
+	 * </pre>
+	 *
+	 * @param throwable    the Throwable to possibly propagate
+	 * @param declaredType the single checked exception type declared by the calling
+	 *                     method
+	 */
+	public static <X extends Throwable> void propagateIfPossible(@Nullable Throwable throwable, Class<X> declaredType)
+			throws X {
+		propagateIfInstanceOf(throwable, declaredType);
+		propagateIfPossible(throwable);
+	}
+
+	/**
+	 * Propagates {@code throwable} exactly as-is, if and only if it is an instance
+	 * of {@link RuntimeException}, {@link Error}, {@code declaredType1}, or
+	 * {@code declaredType2}. In the unlikely case that you have three or more
+	 * declared checked exception types, you can handle them all by invoking these
+	 * methods repeatedly. See usage example in
+	 * {@link #propagateIfPossible(Throwable, Class)}.
+	 *
+	 * @param throwable     the Throwable to possibly propagate
+	 * @param declaredType1 any checked exception type declared by the calling
+	 *                      method
+	 * @param declaredType2 any other checked exception type declared by the calling
+	 *                      method
+	 */
+	public static <X1 extends Throwable, X2 extends Throwable> void propagateIfPossible(@Nullable Throwable throwable,
+			Class<X1> declaredType1, Class<X2> declaredType2) throws X1, X2 {
+		checkNotNull(declaredType2);
+		propagateIfInstanceOf(throwable, declaredType1);
+		propagateIfPossible(throwable, declaredType2);
+	}
+
+	/**
+	 * Propagates {@code throwable} as-is if it is an instance of
+	 * {@link RuntimeException} or {@link Error}, or else as a last resort, wraps it
+	 * in a {@code RuntimeException} then propagates.
+	 * <p>
+	 * This method always throws an exception. The {@code RuntimeException} return
+	 * type is only for client code to make Java type system happy in case a return
+	 * value is required by the enclosing method. Example usage:
+	 * 
+	 * <pre>
+	 * T doSomething() {
+	 * 	try {
+	 * 		return someMethodThatCouldThrowAnything();
+	 * 	} catch (IKnowWhatToDoWithThisException e) {
+	 * 		return handle(e);
+	 * 	} catch (Throwable t) {
+	 * 		throw Throwables.propagate(t);
+	 * 	}
+	 * }
+	 * </pre>
+	 *
+	 * @param throwable the Throwable to propagate
+	 * @return nothing will ever be returned; this return type is only for your
+	 *         convenience, as illustrated in the example above
+	 */
+	public static RuntimeException propagate(Throwable throwable) {
+		propagateIfPossible(checkNotNull(throwable));
+		throw new RuntimeException(throwable);
+	}
+
+	/**
+	 * Returns the innermost cause of {@code throwable}. The first throwable in a
+	 * chain provides context from when the error or exception was initially
+	 * detected. Example usage:
+	 * 
+	 * <pre>
+	 * assertEquals("Unable to assign a customer id", Throwables.getRootCause(e).getMessage());
+	 * </pre>
+	 */
+	public static Throwable getRootCause(Throwable throwable) {
+		Throwable cause;
+		while ((cause = throwable.getCause()) != null) {
+			throwable = cause;
+		}
+		return throwable;
+	}
+
+	/**
+	 * Gets a {@code Throwable} cause chain as a list. The first entry in the list
+	 * will be {@code throwable} followed by its cause hierarchy. Note that this is
+	 * a snapshot of the cause chain and will not reflect any subsequent changes to
+	 * the cause chain.
+	 *
+	 * <p>
+	 * Here's an example of how it can be used to find specific types of exceptions
+	 * in the cause chain:
+	 *
+	 * <pre>
+	 * Iterables.filter(Throwables.getCausalChain(e), IOException.class));
+	 * </pre>
+	 *
+	 * @param throwable the non-null {@code Throwable} to extract causes from
+	 * @return an unmodifiable list containing the cause chain starting with
+	 *         {@code throwable}
+	 */
+	@Beta // TODO(kevinb): decide best return type
+	public static List<Throwable> getCausalChain(Throwable throwable) {
+		checkNotNull(throwable);
+		List<Throwable> causes = new ArrayList<Throwable>(4);
+		while (throwable != null) {
+			causes.add(throwable);
+			throwable = throwable.getCause();
+		}
+		return Collections.unmodifiableList(causes);
+	}
+
+	/**
+	 * Returns a string containing the result of {@link Throwable#toString()
+	 * toString()}, followed by the full, recursive stack trace of
+	 * {@code throwable}. Note that you probably should not be parsing the resulting
+	 * string; if you need programmatic access to the stack frames, you can call
+	 * {@link Throwable#getStackTrace()}.
+	 */
+	public static String getStackTraceAsString(Throwable throwable) {
+		return EagRuntime.getStackTrace(throwable);
+	}
+}

sources/main/java/com/google/common/base/Ticker.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright (C) 2011 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 com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * A time source; returns a time value representing the number of nanoseconds
+ * elapsed since some fixed but arbitrary point in time. Note that most users
+ * should use {@link Stopwatch} instead of interacting with this class directly.
+ *
+ * <p>
+ * <b>Warning:</b> this interface can only be used to measure elapsed time, not
+ * wall time.
+ *
+ * @author Kevin Bourrillion
+ * @since 10.0
+ *        (<a href="http://code.google.com/p/guava-libraries/wiki/Compatibility"
+ *        >mostly source-compatible</a> since 9.0)
+ */
+@Beta
+@GwtCompatible
+public abstract class Ticker {
+	/**
+	 * Constructor for use by subclasses.
+	 */
+	protected Ticker() {
+	}
+
+	/**
+	 * Returns the number of nanoseconds elapsed since this ticker's fixed point of
+	 * reference.
+	 */
+	public abstract long read();
+
+	/**
+	 * A ticker that reads the current time using {@link System#nanoTime}.
+	 *
+	 * @since 10.0
+	 */
+	public static Ticker systemTicker() {
+		return SYSTEM_TICKER;
+	}
+
+	private static final Ticker SYSTEM_TICKER = new Ticker() {
+		@Override
+		public long read() {
+			return Platform.systemNanoTime();
+		}
+	};
+}

sources/main/java/com/google/common/base/Utf8.java

@@ -0,0 +1,206 @@
+/*
+ * Copyright (C) 2013 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.checkPositionIndexes;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Low-level, high-performance utility methods related to the
+ * {@linkplain Charsets#UTF_8 UTF-8} character encoding. UTF-8 is defined in
+ * section D92 of
+ * <a href="http://www.unicode.org/versions/Unicode6.2.0/ch03.pdf">The Unicode
+ * Standard Core Specification, Chapter 3</a>.
+ *
+ * <p>
+ * The variant of UTF-8 implemented by this class is the restricted definition
+ * of UTF-8 introduced in Unicode 3.1. One implication of this is that it
+ * rejects
+ * <a href="http://www.unicode.org/versions/corrigendum1.html">"non-shortest
+ * form"</a> byte sequences, even though the JDK decoder may accept them.
+ *
+ * @author Martin Buchholz
+ * @author Clément Roux
+ * @since 16.0
+ */
+@Beta
+@GwtCompatible
+public final class Utf8 {
+	/**
+	 * Returns the number of bytes in the UTF-8-encoded form of {@code sequence}.
+	 * For a string, this method is equivalent to
+	 * {@code string.getBytes(UTF_8).length}, but is more efficient in both time and
+	 * space.
+	 *
+	 * @throws IllegalArgumentException if {@code sequence} contains ill-formed
+	 *                                  UTF-16 (unpaired surrogates)
+	 */
+	public static int encodedLength(CharSequence sequence) {
+		// Warning to maintainers: this implementation is highly optimized.
+		int utf16Length = sequence.length();
+		int utf8Length = utf16Length;
+		int i = 0;
+
+		// This loop optimizes for pure ASCII.
+		while (i < utf16Length && sequence.charAt(i) < 0x80) {
+			i++;
+		}
+
+		// This loop optimizes for chars less than 0x800.
+		for (; i < utf16Length; i++) {
+			char c = sequence.charAt(i);
+			if (c < 0x800) {
+				utf8Length += ((0x7f - c) >>> 31); // branch free!
+			} else {
+				utf8Length += encodedLengthGeneral(sequence, i);
+				break;
+			}
+		}
+
+		if (utf8Length < utf16Length) {
+			// Necessary and sufficient condition for overflow because of maximum 3x
+			// expansion
+			throw new IllegalArgumentException("UTF-8 length does not fit in int: " + (utf8Length + (1L << 32)));
+		}
+		return utf8Length;
+	}
+
+	private static int encodedLengthGeneral(CharSequence sequence, int start) {
+		int utf16Length = sequence.length();
+		int utf8Length = 0;
+		for (int i = start; i < utf16Length; i++) {
+			char c = sequence.charAt(i);
+			if (c < 0x800) {
+				utf8Length += (0x7f - c) >>> 31; // branch free!
+			} else {
+				utf8Length += 2;
+				// jdk7+: if (Character.isSurrogate(c)) {
+				if (Character.MIN_SURROGATE <= c && c <= Character.MAX_SURROGATE) {
+					// Check that we have a well-formed surrogate pair.
+					int cp = Character.codePointAt(sequence, i);
+					if (cp < Character.MIN_SUPPLEMENTARY_CODE_POINT) {
+						throw new IllegalArgumentException("Unpaired surrogate at index " + i);
+					}
+					i++;
+				}
+			}
+		}
+		return utf8Length;
+	}
+
+	/**
+	 * Returns {@code true} if {@code bytes} is a <i>well-formed</i> UTF-8 byte
+	 * sequence according to Unicode 6.0. Note that this is a stronger criterion
+	 * than simply whether the bytes can be decoded. For example, some versions of
+	 * the JDK decoder will accept "non-shortest form" byte sequences, but encoding
+	 * never reproduces these. Such byte sequences are <i>not</i> considered
+	 * well-formed.
+	 *
+	 * <p>
+	 * This method returns {@code true} if and only if
+	 * {@code Arrays.equals(bytes, new
+	 * String(bytes, UTF_8).getBytes(UTF_8))} does, but is more efficient in both
+	 * time and space.
+	 */
+	public static boolean isWellFormed(byte[] bytes) {
+		return isWellFormed(bytes, 0, bytes.length);
+	}
+
+	/**
+	 * Returns whether the given byte array slice is a well-formed UTF-8 byte
+	 * sequence, as defined by {@link #isWellFormed(byte[])}. Note that this can be
+	 * false even when {@code
+	 * isWellFormed(bytes)} is true.
+	 *
+	 * @param bytes the input buffer
+	 * @param off   the offset in the buffer of the first byte to read
+	 * @param len   the number of bytes to read from the buffer
+	 */
+	public static boolean isWellFormed(byte[] bytes, int off, int len) {
+		int end = off + len;
+		checkPositionIndexes(off, end, bytes.length);
+		// Look for the first non-ASCII character.
+		for (int i = off; i < end; i++) {
+			if (bytes[i] < 0) {
+				return isWellFormedSlowPath(bytes, i, end);
+			}
+		}
+		return true;
+	}
+
+	private static boolean isWellFormedSlowPath(byte[] bytes, int off, int end) {
+		int index = off;
+		while (true) {
+			int byte1;
+
+			// Optimize for interior runs of ASCII bytes.
+			do {
+				if (index >= end) {
+					return true;
+				}
+			} while ((byte1 = bytes[index++]) >= 0);
+
+			if (byte1 < (byte) 0xE0) {
+				// Two-byte form.
+				if (index == end) {
+					return false;
+				}
+				// Simultaneously check for illegal trailing-byte in leading position
+				// and overlong 2-byte form.
+				if (byte1 < (byte) 0xC2 || bytes[index++] > (byte) 0xBF) {
+					return false;
+				}
+			} else if (byte1 < (byte) 0xF0) {
+				// Three-byte form.
+				if (index + 1 >= end) {
+					return false;
+				}
+				int byte2 = bytes[index++];
+				if (byte2 > (byte) 0xBF
+						// Overlong? 5 most significant bits must not all be zero.
+						|| (byte1 == (byte) 0xE0 && byte2 < (byte) 0xA0)
+						// Check for illegal surrogate codepoints.
+						|| (byte1 == (byte) 0xED && (byte) 0xA0 <= byte2)
+						// Third byte trailing-byte test.
+						|| bytes[index++] > (byte) 0xBF) {
+					return false;
+				}
+			} else {
+				// Four-byte form.
+				if (index + 2 >= end) {
+					return false;
+				}
+				int byte2 = bytes[index++];
+				if (byte2 > (byte) 0xBF
+						// Check that 1 <= plane <= 16. Tricky optimized form of:
+						// if (byte1 > (byte) 0xF4
+						// || byte1 == (byte) 0xF0 && byte2 < (byte) 0x90
+						// || byte1 == (byte) 0xF4 && byte2 > (byte) 0x8F)
+						|| (((byte1 << 28) + (byte2 - (byte) 0x90)) >> 30) != 0
+						// Third byte trailing-byte test
+						|| bytes[index++] > (byte) 0xBF
+						// Fourth byte trailing-byte test
+						|| bytes[index++] > (byte) 0xBF) {
+					return false;
+				}
+			}
+		}
+	}
+
+	private Utf8() {
+	}
+}

sources/main/java/com/google/common/base/Verify.java

@@ -0,0 +1,187 @@
+/*
+ * Copyright (C) 2013 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.format;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Static convenience methods that serve the same purpose as Java language
+ * <a href=
+ * "http://docs.oracle.com/javase/7/docs/technotes/guides/language/assert.html">
+ * assertions</a>, except that they are always enabled. These methods should be
+ * used instead of Java assertions whenever there is a chance the check may fail
+ * "in real life". Example:
+ * 
+ * <pre>
+ * {
+ * 	&#64;code
+ *
+ * 	Bill bill = remoteService.getLastUnpaidBill();
+ *
+ * 	// In case bug 12345 happens again we'd rather just die
+ * 	Verify.verify(bill.status() == Status.UNPAID, "Unexpected bill status: %s", bill.status());
+ * }
+ * </pre>
+ *
+ * <h3>Comparison to alternatives</h3>
+ *
+ * <p>
+ * <b>Note:</b> In some cases the differences explained below can be subtle.
+ * When it's unclear which approach to use, <b>don't worry</b> too much about
+ * it; just pick something that seems reasonable and it will be fine.
+ *
+ * <ul>
+ * <li>If checking whether the <i>caller</i> has violated your method or
+ * constructor's contract (such as by passing an invalid argument), use the
+ * utilities of the {@link Preconditions} class instead.
+ *
+ * <li>If checking an <i>impossible</i> condition (which <i>cannot</i> happen
+ * unless your own class or its <i>trusted</i> dependencies is badly broken),
+ * this is what ordinary Java assertions are for. Note that assertions are not
+ * enabled by default; they are essentially considered "compiled comments."
+ *
+ * <li>An explicit {@code if/throw} (as illustrated above) is always acceptable;
+ * we still recommend using our {@link VerifyException} exception type. Throwing
+ * a plain {@link RuntimeException} is frowned upon.
+ *
+ * <li>Use of {@link java.util.Objects#requireNonNull(Object)} is generally
+ * discouraged, since {@link #verifyNotNull(Object)} and
+ * {@link Preconditions#checkNotNull(Object)} perform the same function with
+ * more clarity.
+ * </ul>
+ *
+ * <h3>Warning about performance</h3>
+ *
+ * <p>
+ * Remember that parameter values for message construction must all be computed
+ * eagerly, and autoboxing and varargs array creation may happen as well, even
+ * when the verification succeeds and the message ends up unneeded.
+ * Performance-sensitive verification checks should continue to use usual form:
+ * 
+ * <pre>
+ * {
+ * 	&#64;code
+ *
+ * 	Bill bill = remoteService.getLastUnpaidBill();
+ * 	if (bill.status() != Status.UNPAID) {
+ * 		throw new VerifyException("Unexpected bill status: " + bill.status());
+ * 	}
+ * }
+ * </pre>
+ *
+ * <h3>Only {@code %s} is supported</h3>
+ *
+ * <p>
+ * As with {@link Preconditions} error message template strings, only the
+ * {@code "%s"} specifier is supported, not the full range of
+ * {@link java.util.Formatter} specifiers. However, note that if the number of
+ * arguments does not match the number of occurrences of {@code "%s"} in the
+ * format string, {@code Verify} will still behave as expected, and will still
+ * include all argument values in the error message; the message will simply not
+ * be formatted exactly as intended.
+ *
+ * <h3>More information</h3>
+ *
+ * See <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/ConditionalFailuresExplained">Conditional
+ * failures explained</a> in the Guava User Guide for advice on when this class
+ * should be used.
+ *
+ * @since 17.0
+ */
+@Beta
+@GwtCompatible
+public final class Verify {
+	/**
+	 * Ensures that {@code expression} is {@code true}, throwing a
+	 * {@code VerifyException} with no message otherwise.
+	 */
+	public static void verify(boolean expression) {
+		if (!expression) {
+			throw new VerifyException();
+		}
+	}
+
+	/**
+	 * Ensures that {@code expression} is {@code true}, throwing a
+	 * {@code VerifyException} with a custom message otherwise.
+	 *
+	 * @param expression           a boolean expression
+	 * @param errorMessageTemplate a template for the exception message should the
+	 *                             check fail. The message is formed by replacing
+	 *                             each {@code %s} placeholder in the template with
+	 *                             an argument. These are matched by position - the
+	 *                             first {@code %s} gets
+	 *                             {@code errorMessageArgs[0]}, etc. Unmatched
+	 *                             arguments will be appended to the formatted
+	 *                             message in square braces. Unmatched placeholders
+	 *                             will be left as-is.
+	 * @param errorMessageArgs     the arguments to be substituted into the message
+	 *                             template. Arguments are converted to strings
+	 *                             using {@link String#valueOf(Object)}.
+	 * @throws VerifyException if {@code expression} is {@code false}
+	 */
+	public static void verify(boolean expression, @Nullable String errorMessageTemplate,
+			@Nullable Object... errorMessageArgs) {
+		if (!expression) {
+			throw new VerifyException(format(errorMessageTemplate, errorMessageArgs));
+		}
+	}
+
+	/**
+	 * Ensures that {@code reference} is non-null, throwing a
+	 * {@code VerifyException} with a default message otherwise.
+	 *
+	 * @return {@code reference}, guaranteed to be non-null, for convenience
+	 */
+	public static <T> T verifyNotNull(@Nullable T reference) {
+		return verifyNotNull(reference, "expected a non-null reference");
+	}
+
+	/**
+	 * Ensures that {@code reference} is non-null, throwing a
+	 * {@code VerifyException} with a custom message otherwise.
+	 *
+	 * @param errorMessageTemplate a template for the exception message should the
+	 *                             check fail. The message is formed by replacing
+	 *                             each {@code %s} placeholder in the template with
+	 *                             an argument. These are matched by position - the
+	 *                             first {@code %s} gets
+	 *                             {@code errorMessageArgs[0]}, etc. Unmatched
+	 *                             arguments will be appended to the formatted
+	 *                             message in square braces. Unmatched placeholders
+	 *                             will be left as-is.
+	 * @param errorMessageArgs     the arguments to be substituted into the message
+	 *                             template. Arguments are converted to strings
+	 *                             using {@link String#valueOf(Object)}.
+	 * @return {@code reference}, guaranteed to be non-null, for convenience
+	 */
+	public static <T> T verifyNotNull(@Nullable T reference, @Nullable String errorMessageTemplate,
+			@Nullable Object... errorMessageArgs) {
+		verify(reference != null, errorMessageTemplate, errorMessageArgs);
+		return reference;
+	}
+
+	// TODO(kevinb): consider <T> T verifySingleton(Iterable<T>) to take over for
+	// Iterables.getOnlyElement()
+
+	private Verify() {
+	}
+}

sources/main/java/com/google/common/base/VerifyException.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2013 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 javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+import com.google.common.annotations.GwtCompatible;
+
+/**
+ * Exception thrown upon the failure of a <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/ConditionalFailuresExplained">verification
+ * check</a>, including those performed by the convenience methods of the
+ * {@link Verify} class.
+ *
+ * @since 17.0
+ */
+@Beta
+@GwtCompatible
+public class VerifyException extends RuntimeException {
+	/** Constructs a {@code VerifyException} with no message. */
+	public VerifyException() {
+	}
+
+	/** Constructs a {@code VerifyException} with the message {@code message}. */
+	public VerifyException(@Nullable String message) {
+		super(message);
+	}
+}

sources/main/java/com/google/common/base/package-info.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright (C) 2007 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.
+ */
+
+/**
+ * Basic utility libraries and interfaces.
+ *
+ * <p>
+ * This package is a part of the open-source
+ * <a href="http://guava-libraries.googlecode.com">Guava libraries</a>.
+ *
+ * <h2>Contents</h2>
+ *
+ * <h3>String-related utilities</h3>
+ *
+ * <ul>
+ * <li>{@link com.google.common.base.Ascii}
+ * <li>{@link com.google.common.base.CaseFormat}
+ * <li>{@link com.google.common.base.CharMatcher}
+ * <li>{@link com.google.common.base.Charsets}
+ * <li>{@link com.google.common.base.Joiner}
+ * <li>{@link com.google.common.base.Splitter}
+ * <li>{@link com.google.common.base.Strings}
+ * </ul>
+ *
+ * <h3>Function types</h3>
+ *
+ * <ul>
+ * <li>{@link com.google.common.base.Function},
+ * {@link com.google.common.base.Functions}
+ * <li>{@link com.google.common.base.Predicate},
+ * {@link com.google.common.base.Predicates}
+ * <li>{@link com.google.common.base.Equivalence}
+ * <li>{@link com.google.common.base.Converter}
+ * <li>{@link com.google.common.base.Supplier},
+ * {@link com.google.common.base.Suppliers}
+ * </ul>
+ *
+ * <h3>Other</h3>
+ *
+ * <ul>
+ * <li>{@link com.google.common.base.Defaults}
+ * <li>{@link com.google.common.base.Enums}
+ * <li>{@link com.google.common.base.Objects}
+ * <li>{@link com.google.common.base.Optional}
+ * <li>{@link com.google.common.base.Preconditions}
+ * <li>{@link com.google.common.base.Stopwatch}
+ * <li>{@link com.google.common.base.Throwables}
+ * </ul>
+ *
+ */
+@ParametersAreNonnullByDefault
+package com.google.common.base;
+
+import javax.annotation.ParametersAreNonnullByDefault;