## com.google.common.base
Class Joiner

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

    @GwtCompatible
    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 (imported from Google Collections Library)
Author:
  Kevin Bourrillion

Nested Class Summary
`static class` `Joiner.MapJoiner` An object that joins map entries in the same manner as `Joiner` joins iterables and arrays.

Method Summary

`

`<A extends Appendable,I extends Object & Iterable<?> & 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 Appendable> A`

`

`appendTo(A appendable, Iterable<?> parts)`
Appends the string representation of each of `parts`, using the previously configured separator between each, to `appendable`.

`

`<A extends Appendable> A`

`

`appendTo(A appendable, Iterator<?> parts)`
Appends the string representation of each of `parts`, using the previously configured separator between each, to `appendable`.

`

`<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`.

`

`<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.

`

`<I extends Object & Iterable<?> & Iterator<?>> StringBuilder`

`

`appendTo(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.

`StringBuilder` `appendTo(StringBuilder builder, Iterable<?> parts)` Appends the string representation of each of `parts`, using the previously configured separator between each, to `builder`.
`StringBuilder` `appendTo(StringBuilder builder, Iterator<?> parts)` Appends the string representation of each of `parts`, using the previously configured separator between each, to `builder`.
`StringBuilder` `appendTo(StringBuilder builder, Object[] parts)` Appends the string representation of each of `parts`, using the previously configured separator between each, to `builder`.
`StringBuilder` `appendTo(StringBuilder builder, Object first, Object second, Object... rest)` Appends to `builder` the string representation of each of the remaining arguments.

`

`<I extends Object & Iterable<?> & Iterator<?>> 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.

`String` `join(Iterable<?> parts)` Returns a string containing the string representation of each of `parts`, using the previously configured separator between each.
`String` `join(Iterator<?> parts)` Returns a string containing the string representation of each of `parts`, using the previously configured separator between each.
`String` `join(Object[] parts)` Returns a string containing the string representation of each of `parts`, using the previously configured separator between each.
`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.
`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.
`Joiner` `skipNulls()` Returns a joiner with the same behavior as this joiner, except automatically skipping over any provided null elements.
`Joiner` `useForNull(String nullText)` Returns a joiner with the same behavior as this one, except automatically substituting `nullText` for any provided null elements.
`Joiner.MapJoiner` `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`

Method Detail

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

    @Beta
    @Deprecated
    public final <A extends Appendable,I extends Object & Iterable<?> & Iterator<?>> A appendTo(A appendable,
                                                                                                              I parts)
                                        throws 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:
    `IOException`
  Since:
    11.0

### appendTo

    public <A extends Appendable> A appendTo(A appendable,
                                             Iterable<?> 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<?> 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,
                                                   @Nullable
                                                   Object first,
                                                   @Nullable
                                                   Object second,
                                                   Object... rest)
                                        throws IOException

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

  Throws:
    `IOException`

### appendTo

    @Beta
    @Deprecated
    public final <I extends Object & Iterable<?> & Iterator<?>> StringBuilder appendTo(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 StringBuilder appendTo(StringBuilder builder,
                                        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 StringBuilder appendTo(StringBuilder builder,
                                        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 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,
                                        @Nullable
                                        Object first,
                                        @Nullable
                                        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

    @Beta
    @Deprecated
    public final <I extends Object & Iterable<?> & Iterator<?>> 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 String join(Iterable<?> 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<?> 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(@Nullable
                             Object first,
                             @Nullable
                             Object second,
                             Object... rest)

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

### useForNull

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

    @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(String keyValueSeparator)

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

Copyright © 2010-2012. All Rights Reserved.