/* * 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 com.google.common.annotations.Beta; import com.google.common.annotations.GwtCompatible; 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; /** * 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:
{@code * * Joiner joiner = Joiner.on("; ").skipNulls(); * . . . * return joiner.join("Harry", null, "Ron", "Hermione");}* * This returns the string {@code "Harry; Ron; Hermione"}. Note that all input elements are * converted to strings using {@link Object#toString()} before being appended. * *
If neither {@link #skipNulls()} nor {@link #useForNull(String)} is specified, the joining * methods will throw {@link NullPointerException} if any given element is null. * *
Warning: joiner instances are always immutable; 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.
{@code * * // Bad! Do not do this! * Joiner joiner = Joiner.on(','); * joiner.skipNulls(); // does nothing! * return joiner.join("wrong", null, "wrong");}* * @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; } /** * Deprecated. * * @since 11.0 * @deprecated use {@link #appendTo(Appendable, Iterator)} by casting {@code parts} to * {@code Iterator>}, or better yet, by implementing only {@code Iterator} and not * {@code Iterable}. This method is scheduled for deletion in June 2013. */ @Beta @Deprecated public final & Iterator>> A appendTo(A appendable, I parts) throws IOException { return appendTo(appendable, (Iterator>) parts); } /** * Appends the string representation of each of {@code parts}, using the previously configured * separator between each, to {@code appendable}. */ public 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 */ @Beta public 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 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 appendTo( A appendable, @Nullable Object first, @Nullable Object second, Object... rest) throws IOException { return appendTo(appendable, iterable(first, second, rest)); } /** * Deprecated. * * @since 11.0 * @deprecated use {@link #appendTo(StringBuilder, Iterator)} by casting {@code parts} to * {@code Iterator>}, or better yet, by implementing only {@code Iterator} and not * {@code Iterable}. This method is scheduled for deletion in June 2013. */ @Beta @Deprecated public final & Iterator>> StringBuilder appendTo(StringBuilder builder, I parts) { return appendTo(builder, (Iterator>) parts); } /** * 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 */ @Beta 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)); } /** * Deprecated. * * @since 11.0 * @deprecated use {@link #join(Iterator)} by casting {@code parts} to * {@code Iterator>}, or better yet, by implementing only {@code Iterator} and not * {@code Iterable}. This method is scheduled for deletion in June 2013. */ @Beta @Deprecated public final & Iterator>> String join(I parts) { return join((Iterator>) parts); } /** * 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 */ @Beta 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(Object part) { return (part == null) ? nullText : Joiner.this.toString(part); } @Override public Joiner useForNull(String nullText) { checkNotNull(nullText); // weird: just to satisfy NullPointerTester. 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 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) { checkNotNull(nullText); // weird: just to satisfy NullPointerTester. throw new UnsupportedOperationException("already specified skipNulls"); } @Override public MapJoiner withKeyValueSeparator(String kvs) { checkNotNull(kvs); // weird: just to satisfy NullPointerTester. 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. * *
In addition to operating on {@code Map} instances, {@code MapJoiner} can operate on {@code * Multimap} entries in two distinct modes: * *