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.

Nested and Inner Type Summary

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

Modifier and Type	Field and Description
private final String	separator

Access	Constructor and Description
private	Joiner(String separator)
private	Joiner(Joiner prototype)

Method Summary

Modifier and Type	Method and Description
public <A extends Appendable> A	appendTo(A appendable, Iterable<? extends @Nullable Object> parts) Appends the string representation of each of `parts`, using the previously configured separator between each, to `appendable`.
public <A extends Appendable> A	appendTo(A appendable, Iterator<? extends @Nullable Object> parts) Appends the string representation of each of `parts`, using the previously configured separator between each, to `appendable`.
public final <A extends Appendable> A	appendTo(A appendable, @Nullable Object[] parts) Appends the string representation of each of `parts`, using the previously configured separator between each, to `appendable`.
public final <A extends Appendable> A	appendTo(A appendable, Object first, Object second, @Nullable Object... rest) Appends to `appendable` the string representation of each of the remaining arguments.
public final StringBuilder	appendTo(StringBuilder builder, Iterable<? extends @Nullable Object> parts) Appends the string representation of each of `parts`, using the previously configured separator between each, to `builder`.
public final StringBuilder	appendTo(StringBuilder builder, Iterator<? extends @Nullable Object> parts) Appends the string representation of each of `parts`, using the previously configured separator between each, to `builder`.
public final StringBuilder	appendTo(StringBuilder builder, @Nullable Object[] parts) Appends the string representation of each of `parts`, using the previously configured separator between each, to `builder`.
public final StringBuilder	appendTo(StringBuilder builder, Object first, Object second, @Nullable Object... rest) Appends to `builder` the string representation of each of the remaining arguments.
private static Iterable<@Nullable Object>	iterable(Object first, Object second, @Nullable Object[] rest)
public final String	join(Iterable<? extends @Nullable Object> parts) Returns a string containing the string representation of each of `parts`, using the previously configured separator between each.
public final String	join(Iterator<? extends @Nullable Object> parts) Returns a string containing the string representation of each of `parts`, using the previously configured separator between each.
public final String	join(@Nullable Object[] parts) Returns a string containing the string representation of each of `parts`, using the previously configured separator between each.
public final String	join(Object first, Object second, @Nullable Object... rest) Returns a string containing the string representation of each argument, using the previously configured separator between each.
public static Joiner	on(String separator) Returns a joiner which automatically places `separator` between consecutive elements.
public static Joiner	on(char separator) Returns a joiner which automatically places `separator` between consecutive elements.
public Joiner	skipNulls() Returns a joiner with the same behavior as this joiner, except automatically skipping over any provided null elements.
pack-priv CharSequence	toString(Object part)
public Joiner	useForNull(String nullText) Returns a joiner with the same behavior as this one, except automatically substituting `nullText` for any provided null elements.
public Joiner.MapJoiner	withKeyValueSeparator(char keyValueSeparator) Returns a `MapJoiner` using the given key-value separator, and the same configuration as this `Joiner` otherwise.
public Joiner.MapJoiner	withKeyValueSeparator(String keyValueSeparator) Returns a `MapJoiner` using the given key-value separator, and the same configuration as this `Joiner` otherwise.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

separator	back to summary
private final String separator

Joiner	back to summary
private Joiner(String separator)

Joiner	back to summary
private Joiner(Joiner prototype)

Method Detail

appendTo back to summary

appendTo	back to summary
public <A extends Appendable> A appendTo(A appendable, Iterable<? extends @Nullable Object> parts) throws IOException Appends the string representation of each of `parts`, using the previously configured separator between each, to `appendable`. Annotations @CanIgnoreReturnValue

public <A extends Appendable> A appendTo(A appendable, Iterable<? extends @Nullable Object> parts) throws IOException

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

Annotations

@CanIgnoreReturnValue

appendTo back to summary

appendTo	back to summary
public <A extends Appendable> A appendTo(A appendable, Iterator<? extends @Nullable Object> parts) throws IOException Appends the string representation of each of `parts`, using the previously configured separator between each, to `appendable`. Annotations @CanIgnoreReturnValue Since 11.0

public <A extends Appendable> A appendTo(A appendable, Iterator<? extends @Nullable Object> parts) throws IOException

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

Annotations

@CanIgnoreReturnValue

Since

11.0

appendTo back to summary

appendTo	back to summary
public final <A extends Appendable> A appendTo(A appendable, @Nullable Object[] parts) throws IOException Appends the string representation of each of `parts`, using the previously configured separator between each, to `appendable`. Annotations @CanIgnoreReturnValue

public final <A extends Appendable> A appendTo(A appendable, @Nullable Object[] parts) throws IOException

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

Annotations

@CanIgnoreReturnValue

appendTo back to summary

appendTo	back to summary
public final <A extends Appendable> A appendTo(A appendable, Object first, Object second, @Nullable Object... rest) throws IOException Appends to `appendable` the string representation of each of the remaining arguments. Annotations @CanIgnoreReturnValue

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

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

Annotations

@CanIgnoreReturnValue

appendTo back to summary

appendTo	back to summary
public final StringBuilder appendTo(StringBuilder builder, Iterable<? extends @Nullable 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`. Annotations @CanIgnoreReturnValue

public final StringBuilder appendTo(StringBuilder builder, Iterable<? extends @Nullable 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.

Annotations

@CanIgnoreReturnValue

appendTo back to summary

appendTo	back to summary
public final StringBuilder appendTo(StringBuilder builder, Iterator<? extends @Nullable 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`. Annotations @CanIgnoreReturnValue Since 11.0

public final StringBuilder appendTo(StringBuilder builder, Iterator<? extends @Nullable Object> parts)

Annotations

@CanIgnoreReturnValue

Since

11.0

appendTo back to summary

appendTo	back to summary
public final StringBuilder appendTo(StringBuilder builder, @Nullable 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`. Annotations @CanIgnoreReturnValue

public final StringBuilder appendTo(StringBuilder builder, @Nullable Object[] parts)

Annotations

@CanIgnoreReturnValue

appendTo back to summary

appendTo	back to summary
public final StringBuilder appendTo(StringBuilder builder, Object first, Object second, @Nullable 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`. Annotations @CanIgnoreReturnValue

public final StringBuilder appendTo(StringBuilder builder, Object first, Object second, @Nullable 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.

Annotations

@CanIgnoreReturnValue

iterable	back to summary
private static Iterable<@Nullable Object> iterable(Object first, Object second, @Nullable Object[] rest)

join	back to summary
public final String join(Iterable<? extends @Nullable Object> parts) Returns a string containing the string representation of each of `parts`, using the previously configured separator between each.

join back to summary

join	back to summary
public final String join(Iterator<? extends @Nullable Object> parts) Returns a string containing the string representation of each of `parts`, using the previously configured separator between each. Since 11.0

public final String join(Iterator<? extends @Nullable Object> parts)

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

Since: 11.0

join	back to summary
public final String join(@Nullable Object[] parts) Returns a string containing the string representation of each of `parts`, using the previously configured separator between each.

join	back to summary
public final String join(Object first, Object second, @Nullable Object... rest) Returns a string containing the string representation of each argument, using the previously configured separator between each.

on	back to summary
public static Joiner on(String separator) Returns a joiner which automatically places `separator` between consecutive elements.

on	back to summary
public static Joiner on(char separator) Returns a joiner which automatically places `separator` between consecutive elements.

skipNulls	back to summary
public Joiner skipNulls() Returns a joiner with the same behavior as this joiner, except automatically skipping over any provided null elements.

toString	back to summary
pack-priv CharSequence toString(Object part)

useForNull	back to summary
public Joiner useForNull(String nullText) Returns a joiner with the same behavior as this one, except automatically substituting `nullText` for any provided null elements.

withKeyValueSeparator back to summary

withKeyValueSeparator	back to summary
public Joiner.MapJoiner withKeyValueSeparator(char keyValueSeparator) Returns a `MapJoiner` using the given key-value separator, and the same configuration as this `Joiner` otherwise. Since 20.0

public Joiner.MapJoiner withKeyValueSeparator(char keyValueSeparator)

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

Since: 20.0

withKeyValueSeparator	back to summary
public Joiner.MapJoiner withKeyValueSeparator(String keyValueSeparator) Returns a `MapJoiner` using the given key-value separator, and the same configuration as this `Joiner` otherwise.

com.google.common.base back to summary

public final Class Joiner.MapJoiner

Class Inheritance

extends Object

java.lang.Object
com.google.common.base.Joiner.MapJoiner

An object that joins map entries in the same manner as Joiner joins iterables and arrays. Like Joiner, it is thread-safe and immutable.

In addition to operating on Map instances, MapJoiner can operate on Multimap entries in two distinct modes:

To output a separate entry for each key-value pair, pass multimap.entries() to a MapJoiner method that accepts entries as input, and receive output of the form key1=A&key1=B&key2=C.
To output a single entry for each key, pass multimap.asMap() to a MapJoiner method that accepts a map as input, and receive output of the form key1=[A, B]&key2=C.

Since: 2.0

Field Summary

Modifier and Type	Field and Description
private final Joiner	joiner
private final String	keyValueSeparator

Constructor Summary

Access	Constructor and Description
private	MapJoiner(Joiner joiner, String keyValueSeparator)

Method Summary

Modifier and Type	Method and Description
public <A extends Appendable> A	appendTo(A appendable, Map<?, ?> map) Appends the string representation of each entry of `map`, using the previously configured separator and key-value separator, to `appendable`.
public StringBuilder	appendTo(StringBuilder builder, Map<?, ?> map) Appends the string representation of each entry of `map`, using the previously configured separator and key-value separator, to `builder`.
public <A extends Appendable> A	appendTo(A appendable, Iterable<? extends Map.Entry<?, ?>> entries) Appends the string representation of each entry in `entries`, using the previously configured separator and key-value separator, to `appendable`.
public <A extends Appendable> A	appendTo(A appendable, Iterator<? extends Map.Entry<?, ?>> parts) Appends the string representation of each entry in `entries`, using the previously configured separator and key-value separator, to `appendable`.
public StringBuilder	appendTo(StringBuilder builder, Iterable<? extends Map.Entry<?, ?>> entries) Appends the string representation of each entry in `entries`, using the previously configured separator and key-value separator, to `builder`.
public StringBuilder	appendTo(StringBuilder builder, Iterator<? extends Map.Entry<?, ?>> entries) Appends the string representation of each entry in `entries`, using the previously configured separator and key-value separator, to `builder`.
public String	join(Map<?, ?> map) Returns a string containing the string representation of each entry of `map`, using the previously configured separator and key-value separator.
public String	join(Iterable<? extends Map.Entry<?, ?>> entries) Returns a string containing the string representation of each entry in `entries`, using the previously configured separator and key-value separator.
public String	join(Iterator<? extends Map.Entry<?, ?>> entries) Returns a string containing the string representation of each entry in `entries`, using the previously configured separator and key-value separator.
public Joiner.MapJoiner	useForNull(String nullText) Returns a map joiner with the same behavior as this one, except automatically substituting `nullText` for any provided null keys or values.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

joiner	back to summary
private final Joiner joiner

keyValueSeparator	back to summary
private final String keyValueSeparator

Constructor Detail

MapJoiner	back to summary
private MapJoiner(Joiner joiner, String keyValueSeparator)

Method Detail

appendTo back to summary

appendTo	back to summary
public <A extends Appendable> A appendTo(A appendable, Map<?, ?> map) throws IOException Appends the string representation of each entry of `map`, using the previously configured separator and key-value separator, to `appendable`. Annotations @CanIgnoreReturnValue

public <A extends Appendable> A appendTo(A appendable, Map<?, ?> map) throws IOException

Appends the string representation of each entry of map, using the previously configured separator and key-value separator, to appendable.

Annotations

@CanIgnoreReturnValue

appendTo back to summary

appendTo	back to summary
public StringBuilder appendTo(StringBuilder builder, Map<?, ?> map) Appends the string representation of each entry of `map`, using the previously configured separator and key-value separator, to `builder`. Identical to `appendTo(Appendable, Map)`, except that it does not throw `IOException`. Annotations @CanIgnoreReturnValue

public StringBuilder appendTo(StringBuilder builder, Map<?, ?> map)

Appends the string representation of each entry of map, using the previously configured separator and key-value separator, to builder. Identical to appendTo(Appendable, Map), except that it does not throw IOException.

Annotations

@CanIgnoreReturnValue

appendTo back to summary

appendTo	back to summary
public <A extends Appendable> A appendTo(A appendable, Iterable<? extends Map.Entry<?, ?>> entries) throws IOException Appends the string representation of each entry in `entries`, using the previously configured separator and key-value separator, to `appendable`. Annotations @CanIgnoreReturnValue Since 10.0

public <A extends Appendable> A appendTo(A appendable, Iterable<? extends Map.Entry<?, ?>> entries) throws IOException

Appends the string representation of each entry in entries, using the previously configured separator and key-value separator, to appendable.

Annotations

@CanIgnoreReturnValue

Since

10.0

appendTo back to summary

appendTo	back to summary
public <A extends Appendable> A appendTo(A appendable, Iterator<? extends Map.Entry<?, ?>> parts) throws IOException Appends the string representation of each entry in `entries`, using the previously configured separator and key-value separator, to `appendable`. Annotations @CanIgnoreReturnValue Since 11.0

public <A extends Appendable> A appendTo(A appendable, Iterator<? extends Map.Entry<?, ?>> parts) throws IOException

Appends the string representation of each entry in entries, using the previously configured separator and key-value separator, to appendable.

Annotations

@CanIgnoreReturnValue

Since

11.0

appendTo back to summary

appendTo	back to summary
public StringBuilder appendTo(StringBuilder builder, Iterable<? extends Map.Entry<?, ?>> entries) Appends the string representation of each entry in `entries`, using the previously configured separator and key-value separator, to `builder`. Identical to `appendTo(Appendable, Iterable)`, except that it does not throw `IOException`. Annotations @CanIgnoreReturnValue Since 10.0

public StringBuilder appendTo(StringBuilder builder, Iterable<? extends Map.Entry<?, ?>> entries)

Appends the string representation of each entry in entries, using the previously configured separator and key-value separator, to builder. Identical to appendTo(Appendable, Iterable), except that it does not throw IOException.

Annotations

@CanIgnoreReturnValue

Since

10.0

appendTo back to summary

appendTo	back to summary
public StringBuilder appendTo(StringBuilder builder, Iterator<? extends Map.Entry<?, ?>> entries) Appends the string representation of each entry in `entries`, using the previously configured separator and key-value separator, to `builder`. Identical to `appendTo(Appendable, Iterable)`, except that it does not throw `IOException`. Annotations @CanIgnoreReturnValue Since 11.0

public StringBuilder appendTo(StringBuilder builder, Iterator<? extends Map.Entry<?, ?>> entries)

Annotations

@CanIgnoreReturnValue

Since

11.0

join	back to summary
public String join(Map<?, ?> map) Returns a string containing the string representation of each entry of `map`, using the previously configured separator and key-value separator.

join back to summary

join	back to summary
public String join(Iterable<? extends Map.Entry<?, ?>> entries) Returns a string containing the string representation of each entry in `entries`, using the previously configured separator and key-value separator. Since 10.0

public String join(Iterable<? extends Map.Entry<?, ?>> entries)

Returns a string containing the string representation of each entry in entries, using the previously configured separator and key-value separator.

Since: 10.0

join back to summary

join	back to summary
public String join(Iterator<? extends Map.Entry<?, ?>> entries) Returns a string containing the string representation of each entry in `entries`, using the previously configured separator and key-value separator. Since 11.0

public String join(Iterator<? extends Map.Entry<?, ?>> entries)

Returns a string containing the string representation of each entry in entries, using the previously configured separator and key-value separator.

Since: 11.0

useForNull	back to summary
public Joiner.MapJoiner useForNull(String nullText) Returns a map joiner with the same behavior as this one, except automatically substituting `nullText` for any provided null keys or values.

public Class Joiner

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Class Joiner.MapJoiner

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail