Class Joiner

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

public class Joiner extends 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
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    An object that joins map entries in the same manner as Joiner joins iterables and arrays.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final String
     
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Joiner(Joiner prototype)
     
    private
    Joiner(String separator)
     
  • Method Summary

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

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • separator

      private final String separator
  • Constructor Details

    • Joiner

      private Joiner(String separator)
    • Joiner

      private Joiner(Joiner prototype)
  • Method Details

    • on

      public static Joiner on(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

      public <A extends Appendable> A appendTo(A appendable, Iterable<? extends Object> parts) throws IOException
      Appends the string representation of each of parts, using the previously configured separator between each, to appendable.
      Throws:
      IOException
    • appendTo

      public <A extends Appendable> A appendTo(A appendable, Iterator<? extends Object> parts) throws IOException
      Appends the string representation of each of parts, using the previously configured separator between each, to appendable.
      Throws:
      IOException
      Since:
      11.0
    • appendTo

      public final <A extends Appendable> A appendTo(A appendable, Object[] parts) throws IOException
      Appends the string representation of each of parts, using the previously configured separator between each, to appendable.
      Throws:
      IOException
    • appendTo

      public final <A extends Appendable> A appendTo(A appendable, @CheckForNull Object first, @CheckForNull Object second, Object... rest) throws IOException
      Appends to appendable the string representation of each of the remaining arguments.
      Throws:
      IOException
    • appendTo

      public final StringBuilder appendTo(StringBuilder builder, Iterable<? extends 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 StringBuilder appendTo(StringBuilder builder, Iterator<? extends 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.
      Since:
      11.0
    • appendTo

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

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

      public final String join(Iterator<? extends Object> 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 String join(Object[] parts)
      Returns a string containing the string representation of each of parts, using the previously configured separator between each.
    • join

      public final String join(@CheckForNull Object first, @CheckForNull Object second, Object... rest)
      Returns a string containing the string representation of each argument, using the previously configured separator between each.
    • useForNull

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

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

      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

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

      CharSequence toString(@CheckForNull Object part)
    • iterable

      private static Iterable<Object> iterable(@CheckForNull Object first, @CheckForNull Object second, Object[] rest)