Joiner
Date: 2016-05-24

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

- - ### 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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `<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.
    `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.
    `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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### on

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

      Returns a joiner which automatically places `separator` between consecutive elements.

    - #### on

          @CheckReturnValue
          public static Joiner on(char separator)

      Returns a joiner which automatically places `separator` between consecutive elements.

    - #### 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

          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

          @CheckReturnValue
          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

          @CheckReturnValue
          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

          @CheckReturnValue
          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

          @CheckReturnValue
          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.