Package com.google.common.base

Class 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
    Author:
    Kevin Bourrillion

    • Nested Class Summary

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

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      <A extends java.lang.Appendable>
      A      		 appendTo​(A appendable, @Nullable 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.Iterable<? extends @Nullable 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, @Nullable java.lang.Object... rest)
      Appends to appendable the string representation of each of the remaining arguments.
      <A extends java.lang.Appendable>
      A      		 appendTo​(A appendable, java.util.Iterator<? extends @Nullable java.lang.Object> parts)
      Appends the string representation of each of parts, using the previously configured separator between each, to appendable.
      java.lang.StringBuilder appendTo​(java.lang.StringBuilder builder, @Nullable 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.Iterable<? extends @Nullable 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, @Nullable java.lang.Object... rest)
      Appends to builder the string representation of each of the remaining arguments.
      java.lang.StringBuilder appendTo​(java.lang.StringBuilder builder, java.util.Iterator<? extends @Nullable java.lang.Object> parts)
      Appends the string representation of each of parts, using the previously configured separator between each, to builder.
      java.lang.String join​(@Nullable 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.Iterable<? extends @Nullable 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, @Nullable java.lang.Object... rest)
      Returns a string containing the string representation of each argument, using the previously configured separator between each.
      java.lang.String join​(java.util.Iterator<? extends @Nullable java.lang.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​(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​(char keyValueSeparator)
      Returns a MapJoiner using the given key-value separator, and the same configuration as this Joiner otherwise.
      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

        clone, equals, finalize, 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

        @CanIgnoreReturnValue
public <A extends java.lang.Appendable> A appendTo​(A appendable,
                                                   java.lang.Iterable<? extends @Nullable 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

        @CanIgnoreReturnValue
public <A extends java.lang.Appendable> A appendTo​(A appendable,
                                                   java.util.Iterator<? extends @Nullable 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
        Since:
        11.0

      • appendTo

        @CanIgnoreReturnValue
public final <A extends java.lang.Appendable> A appendTo​(A appendable,
                                                         @Nullable 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

        @CanIgnoreReturnValue
public final <A extends java.lang.Appendable> A appendTo​(A appendable,
                                                         @CheckForNull
                                                         java.lang.Object first,
                                                         @CheckForNull
                                                         java.lang.Object second,
                                                         @Nullable 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

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

        @CanIgnoreReturnValue
public final java.lang.StringBuilder appendTo​(java.lang.StringBuilder builder,
                                              java.util.Iterator<? extends @Nullable 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.
        Since:
        11.0

      • appendTo

        @CanIgnoreReturnValue
public final java.lang.StringBuilder appendTo​(java.lang.StringBuilder builder,
                                              @Nullable 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.

      • join

        public final java.lang.String join​(java.lang.Iterable<? extends @Nullable 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​(java.util.Iterator<? extends @Nullable java.lang.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 java.lang.String join​(@Nullable 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​(@CheckForNull
                                   java.lang.Object first,
                                   @CheckForNull
                                   java.lang.Object second,
                                   @Nullable java.lang.Object... rest)
        Returns a string containing the string representation of each argument, using the previously configured separator between each.

      • useForNull

        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

        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​(java.lang.String keyValueSeparator)
        Returns a MapJoiner using the given key-value separator, and the same configuration as this Joiner otherwise.