com.google.common.base

Class Joiner

java.lang.Object

com.google.common.base.Joiner

@GwtCompatible
public class Joiner
extends java.lang.Object

An object which joins pieces of text (specified as an array, Iterable, varargs or even a Map) with a separator. It either appends the results to an Appendable or returns them as a String. Example:

   

   Joiner joiner = Joiner.on("; ").skipNulls();
    . . .
   return joiner.join("Harry", null, "Ron", "Hermione");

This returns the string "Harry; Ron; Hermione". Note that all input elements are converted to strings using Object.toString() before being appended.

If neither skipNulls() nor useForNull(String) is specified, the joining methods will throw NullPointerException if any given element is null.

Warning: joiner instances are always immutable; a configuration method such as 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 static final constants.

   

   // Bad! Do not do this!
   Joiner joiner = Joiner.on(',');
   joiner.skipNulls(); // does nothing!
   return joiner.join("wrong", null, "wrong");

See the Guava User Guide article on Joiner.

Since:

2.0 (imported from Google Collections Library)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Joiner.MapJoiner An object that joins map entries in the same manner as Joiner joins iterables and arrays.

Method Summary

Modifier and Type	Method and Description
<A extends java.lang.Appendable,I extends java.lang.Object & java.lang.Iterable<?> & java.util.Iterator<?>> A	appendTo(A appendable, I parts) Deprecated. use appendTo(Appendable, Iterator) by casting parts to Iterator<?>, or better yet, by implementing only Iterator and not Iterable. This method is scheduled for deletion in June 2013.
<A extends java.lang.Appendable> A	appendTo(A appendable, java.lang.Iterable<?> parts) Appends the string representation of each of parts, using the previously configured separator between each, to appendable.
<A extends java.lang.Appendable> A	appendTo(A appendable, java.util.Iterator<?> parts) Appends the string representation of each of parts, using the previously configured separator between each, to appendable.
<A extends java.lang.Appendable> A	appendTo(A appendable, java.lang.Object[] parts) Appends the string representation of each of parts, using the previously configured separator between each, to appendable.
<A extends java.lang.Appendable> A	appendTo(A appendable, java.lang.Object first, java.lang.Object second, java.lang.Object... rest) Appends to appendable the string representation of each of the remaining arguments.
<I extends java.lang.Object & java.lang.Iterable<?> & java.util.Iterator<?>> java.lang.StringBuilder	appendTo(java.lang.StringBuilder builder, I parts) Deprecated. use appendTo(StringBuilder, Iterator) by casting parts to Iterator<?>, or better yet, by implementing only Iterator and not Iterable. This method is scheduled for deletion in June 2013.
java.lang.StringBuilder	appendTo(java.lang.StringBuilder builder, java.lang.Iterable<?> parts) Appends the string representation of each of parts, using the previously configured separator between each, to builder.
java.lang.StringBuilder	appendTo(java.lang.StringBuilder builder, java.util.Iterator<?> parts) Appends the string representation of each of parts, using the previously configured separator between each, to builder.
java.lang.StringBuilder	appendTo(java.lang.StringBuilder builder, java.lang.Object[] parts) Appends the string representation of each of parts, using the previously configured separator between each, to builder.
java.lang.StringBuilder	appendTo(java.lang.StringBuilder builder, java.lang.Object first, java.lang.Object second, java.lang.Object... rest) Appends to builder the string representation of each of the remaining arguments.
<I extends java.lang.Object & java.lang.Iterable<?> & java.util.Iterator<?>> java.lang.String	join(I parts) Deprecated. use join(Iterator) by casting parts to Iterator<?>, or better yet, by implementing only Iterator and not Iterable. This method is scheduled for deletion in June 2013.
java.lang.String	join(java.lang.Iterable<?> parts) Returns a string containing the string representation of each of parts, using the previously configured separator between each.
java.lang.String	join(java.util.Iterator<?> parts) Returns a string containing the string representation of each of parts, using the previously configured separator between each.
java.lang.String	join(java.lang.Object[] parts) Returns a string containing the string representation of each of parts, using the previously configured separator between each.
java.lang.String	join(java.lang.Object first, java.lang.Object second, java.lang.Object... rest) Returns a string containing the string representation of each argument, using the previously configured separator between each.
static Joiner	on(char separator) Returns a joiner which automatically places separator between consecutive elements.
static Joiner	on(java.lang.String separator) Returns a joiner which automatically places separator between consecutive elements.
Joiner	skipNulls() Returns a joiner with the same behavior as this joiner, except automatically skipping over any provided null elements.
Joiner	useForNull(java.lang.String nullText) Returns a joiner with the same behavior as this one, except automatically substituting nullText for any provided null elements.
Joiner.MapJoiner	withKeyValueSeparator(java.lang.String keyValueSeparator) Returns a MapJoiner using the given key-value separator, and the same configuration as this Joiner otherwise.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

on

public static Joiner on(java.lang.String separator)

Returns a joiner which automatically places separator between consecutive elements.

on

public static Joiner on(char separator)

Returns a joiner which automatically places separator between consecutive elements.

appendTo

@Beta
 @Deprecated
public final <A extends java.lang.Appendable,I extends java.lang.Object & java.lang.Iterable<?> & java.util.Iterator<?>> A appendTo(A appendable,
                                                                                                                                                       I parts)
                                                                                                                                                throws java.io.IOException

Deprecated. use appendTo(Appendable, Iterator) by casting parts to Iterator<?>, or better yet, by implementing only Iterator and not Iterable. This method is scheduled for deletion in June 2013.

Deprecated.

Throws:

java.io.IOException

Since:

11.0

appendTo

public <A extends java.lang.Appendable> A appendTo(A appendable,
                                                   java.lang.Iterable<?> parts)
                                            throws java.io.IOException

Appends the string representation of each of parts, using the previously configured separator between each, to appendable.

Throws:

java.io.IOException

appendTo

public <A extends java.lang.Appendable> A appendTo(A appendable,
                                                   java.util.Iterator<?> parts)
                                            throws java.io.IOException

Appends the string representation of each of parts, using the previously configured separator between each, to appendable.

Throws:

java.io.IOException

Since:

11.0

appendTo

public final <A extends java.lang.Appendable> A appendTo(A appendable,
                                                         java.lang.Object[] parts)
                                                  throws java.io.IOException

Appends the string representation of each of parts, using the previously configured separator between each, to appendable.

Throws:

java.io.IOException

appendTo

public final <A extends java.lang.Appendable> A appendTo(A appendable,
                                                         @Nullable
                                                         java.lang.Object first,
                                                         @Nullable
                                                         java.lang.Object second,
                                                         java.lang.Object... rest)
                                                  throws java.io.IOException

Appends to appendable the string representation of each of the remaining arguments.

Throws:

java.io.IOException

appendTo

@Beta
 @Deprecated
public final <I extends java.lang.Object & java.lang.Iterable<?> & java.util.Iterator<?>> java.lang.StringBuilder appendTo(java.lang.StringBuilder builder,
                                                                                                                                              I parts)

Deprecated. use appendTo(StringBuilder, Iterator) by casting parts to Iterator<?>, or better yet, by implementing only Iterator and not Iterable. This method is scheduled for deletion in June 2013.

Deprecated.

Since:

11.0

appendTo

public final java.lang.StringBuilder appendTo(java.lang.StringBuilder builder,
                                              java.lang.Iterable<?> parts)

Appends the string representation of each of parts, using the previously configured separator between each, to builder. Identical to appendTo(Appendable, Iterable), except that it does not throw IOException.

appendTo

public final java.lang.StringBuilder appendTo(java.lang.StringBuilder builder,
                                              java.util.Iterator<?> parts)

Appends the string representation of each of parts, using the previously configured separator between each, to builder. Identical to appendTo(Appendable, Iterable), except that it does not throw IOException.

Since:

11.0

appendTo

public final java.lang.StringBuilder appendTo(java.lang.StringBuilder builder,
                                              java.lang.Object[] parts)

Appends the string representation of each of parts, using the previously configured separator between each, to builder. Identical to appendTo(Appendable, Iterable), except that it does not throw IOException.

appendTo

public final java.lang.StringBuilder appendTo(java.lang.StringBuilder builder,
                                              @Nullable
                                              java.lang.Object first,
                                              @Nullable
                                              java.lang.Object second,
                                              java.lang.Object... rest)

Appends to builder the string representation of each of the remaining arguments. Identical to appendTo(Appendable, Object, Object, Object...), except that it does not throw IOException.

join

@Beta
 @Deprecated
public final <I extends java.lang.Object & java.lang.Iterable<?> & java.util.Iterator<?>> java.lang.String join(I parts)

Deprecated. use join(Iterator) by casting parts to Iterator<?>, or better yet, by implementing only Iterator and not Iterable. This method is scheduled for deletion in June 2013.

Deprecated.

Since:

11.0

join

public final java.lang.String join(java.lang.Iterable<?> parts)

Returns a string containing the string representation of each of parts, using the previously configured separator between each.

join

public final java.lang.String join(java.util.Iterator<?> parts)

Returns a string containing the string representation of each of parts, using the previously configured separator between each.

Since:

11.0

join

public final java.lang.String join(java.lang.Object[] parts)

Returns a string containing the string representation of each of parts, using the previously configured separator between each.

join

public final java.lang.String join(@Nullable
                                   java.lang.Object first,
                                   @Nullable
                                   java.lang.Object second,
                                   java.lang.Object... rest)

Returns a string containing the string representation of each argument, using the previously configured separator between each.

useForNull

@CheckReturnValue
public Joiner useForNull(java.lang.String nullText)

Returns a joiner with the same behavior as this one, except automatically substituting nullText for any provided null elements.

skipNulls

@CheckReturnValue
public Joiner skipNulls()

Returns a joiner with the same behavior as this joiner, except automatically skipping over any provided null elements.

withKeyValueSeparator

@CheckReturnValue
public Joiner.MapJoiner withKeyValueSeparator(java.lang.String keyValueSeparator)

Returns a MapJoiner using the given key-value separator, and the same configuration as this Joiner otherwise.