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

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

package com.google.common.base;

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

import java.io.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];
				}
			}
		};
	}
}