com.google.common.base
Class Join

java.lang.Object
  extended by com.google.common.base.Join

public final class Join
extends Object

Join is the only utility for joining pieces of text separated by a delimiter that you will ever need. It can handle Iterators, Collections, arrays, and varargs, and can append to any Appendable or just return a String.

A trivial example: join(":", "a", "b", "c") gives "a:b:c". See JoinTest for more examples.

All the methods of this class throw NullPointerException when a value of null is supplied for any parameter. The elements within the collection, iterator, array, or varargs parameter list may be null -- these will be represented in the output with the string "null".

Author:
Kevin Bourrillion

Nested Class Summary
static class Join.JoinException
          Thrown in response to an IOException from the supplied Appendable.
 
Method Summary
static String join(String delimiter, Iterable<?> tokens)
          Returns a String containing the tokens, converted to Strings if necessary, separated by delimiter.
static String join(String delimiter, Iterator<?> tokens)
          Variant of join(String,Iterable) where tokens is an Iterator.
static String join(String delimiter, Object[] tokens)
          Variant of join(String,Iterable) where tokens is an array.
static String join(String delimiter, Object firstToken, Object... otherTokens)
          Variant of join(String,Iterable) for tokens given using varargs.
static
<T extends Appendable>
T
join(T appendable, String delimiter, Iterable<?> tokens)
          Variant of join(Appendable,String,Iterator) where tokens is an Iterable.
static
<T extends Appendable>
T
join(T appendable, String delimiter, Iterator<?> tokens)
          Appends each of the tokens to appendable, separated by delimiter.
static
<T extends Appendable>
T
join(T appendable, String delimiter, Object[] tokens)
          Variant of join(Appendable,String,Iterator) where tokens is an array.
static
<T extends Appendable>
T
join(T appendable, String delimiter, Object firstToken, Object... otherTokens)
          Variant of join(Appendable,String,Iterator) for tokens given using varargs.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

join

public static <T extends Appendable> T join(T appendable,
                                            String delimiter,
                                            Iterator<?> tokens)
Appends each of the tokens to appendable, separated by delimiter.

Parameters:
appendable - the non-null object to append the results to
delimiter - a non-null String to append between every element, but not at the beginning or end
tokens - Objects of any type. For each element, if it is an instance of CharSequence it will be appended as-is, otherwise it will be converted to a CharSequence using String.valueOf(Object). Note that this implies that null tokens will be appended as the four-character string "null".
Returns:
The same appendable instance that was passed in
Throws:
Join.JoinException - if an IOException occurs

join

public static String join(String delimiter,
                          Iterable<?> tokens)
Returns a String containing the tokens, converted to Strings if necessary, separated by delimiter. If tokens is empty, returns the empty string.


join

public static <T extends Appendable> T join(T appendable,
                                            String delimiter,
                                            Iterable<?> tokens)
Variant of join(Appendable,String,Iterator) where tokens is an Iterable.


join

public static <T extends Appendable> T join(T appendable,
                                            String delimiter,
                                            Object[] tokens)
Variant of join(Appendable,String,Iterator) where tokens is an array.


join

public static <T extends Appendable> T join(T appendable,
                                            String delimiter,
                                            @Nullable
                                            Object firstToken,
                                            Object... otherTokens)
Variant of join(Appendable,String,Iterator) for tokens given using varargs.


join

public static String join(String delimiter,
                          Iterator<?> tokens)
Variant of join(String,Iterable) where tokens is an Iterator.


join

public static String join(String delimiter,
                          Object[] tokens)
Variant of join(String,Iterable) where tokens is an array.


join

public static String join(String delimiter,
                          @Nullable
                          Object firstToken,
                          Object... otherTokens)
Variant of join(String,Iterable) for tokens given using varargs.