com.google.inject.internal.util
Class Join

java.lang.Object
  com.google.inject.internal.util.Join

public final class Join
extends Object

Utility for joining pieces of text separated by a delimiter. It can handle iterators, collections, arrays, and varargs, and can append to any Appendable or just return a String. For example, join(":", "a", "b", "c") returns "a:b:c".

All 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 by the string "null".

Author:

Kevin Bourrillion

Nested Class Summary

static class

Join.JoinException Exception 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) Returns a string containing the tokens, converted to strings if necessary, separated by delimiter.
static String	join(String delimiter, Object[] tokens) Returns a string containing the tokens, converted to strings if necessary, separated by delimiter.
static String	join(String delimiter, Object firstToken, Object... otherTokens) Returns a string containing the tokens, converted to strings if necessary, separated by delimiter.
static String	join(String keyValueSeparator, String entryDelimiter, Map<?,?> map) Returns a string containing the contents of map, with entries separated by entryDelimiter, and keys and values separated with keyValueSeparator.
static <T extends Appendable> T	join(T appendable, String delimiter, Iterable<?> tokens) Appends each of the tokens to appendable, separated by delimiter.
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) Appends each of the tokens to appendable, separated by delimiter.
static <T extends Appendable> T	join(T appendable, String delimiter, Object firstToken, Object... otherTokens) Appends each of the tokens to appendable, separated by delimiter.
static <T extends Appendable> T	join(T appendable, String keyValueSeparator, String entryDelimiter, Map<?,?> map) Appends the contents of map to appendable, with entries separated by entryDelimiter, and keys and values separated with keyValueSeparator.

Methods inherited from class java.lang.Object

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

Method Detail

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, it returns an empty string.

Each token will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

delimiter - a string to append between every element, but not at the beginning or end

tokens - objects to append

Returns:

a string consisting of the joined elements

join

public static String join(String delimiter,
                          Object[] tokens)

Returns a string containing the tokens, converted to strings if necessary, separated by delimiter. If tokens is empty, it returns an empty string.

Each token will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

delimiter - a string to append between every element, but not at the beginning or end

tokens - objects to append

Returns:

a string consisting of the joined elements

join

public static String join(String delimiter,
                          @Nullable
                          Object firstToken,
                          Object... otherTokens)

Returns a string containing the tokens, converted to strings if necessary, separated by delimiter.

Each token will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

delimiter - a string to append between every element, but not at the beginning or end

firstToken - the first object to append

otherTokens - subsequent objects to append

Returns:

a string consisting of the joined elements

join

public static String join(String delimiter,
                          Iterator<?> tokens)

Returns a string containing the tokens, converted to strings if necessary, separated by delimiter. If tokens is empty, it returns an empty string.

Each token will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

delimiter - a string to append between every element, but not at the beginning or end

tokens - objects to append

Returns:

a string consisting of the joined elements

join

public static String join(String keyValueSeparator,
                          String entryDelimiter,
                          Map<?,?> map)

Returns a string containing the contents of map, with entries separated by entryDelimiter, and keys and values separated with keyValueSeparator.

Each key and value will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

keyValueSeparator - a string to append between every key and its associated value

entryDelimiter - a string to append between every entry, but not at the beginning or end

map - the map containing the data to join

Returns:

a string consisting of the joined entries of the map; empty if the map is empty

join

public static <T extends Appendable> T join(T appendable,
                                            String delimiter,
                                            Iterable<?> tokens)

Appends each of the tokens to appendable, separated by delimiter.

Each token will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

appendable - the object to append the results to

delimiter - a string to append between every element, but not at the beginning or end

tokens - objects to append

Returns:

the same Appendable instance that was passed in

Throws:

Join.JoinException - if an IOException occurs

join

public static <T extends Appendable> T join(T appendable,
                                            String delimiter,
                                            Object[] tokens)

Appends each of the tokens to appendable, separated by delimiter.

Each token will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

appendable - the object to append the results to

delimiter - a string to append between every element, but not at the beginning or end

tokens - objects to append

Returns:

the same Appendable instance that was passed in

Throws:

Join.JoinException - if an IOException occurs

join

public static <T extends Appendable> T join(T appendable,
                                            String delimiter,
                                            @Nullable
                                            Object firstToken,
                                            Object... otherTokens)

Appends each of the tokens to appendable, separated by delimiter.

Each token will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

appendable - the object to append the results to

delimiter - a string to append between every element, but not at the beginning or end

firstToken - the first object to append

otherTokens - subsequent objects to append

Returns:

the same Appendable instance that was passed in

Throws:

Join.JoinException - if an IOException occurs

join

public static <T extends Appendable> T join(T appendable,
                                            String delimiter,
                                            Iterator<?> tokens)

Appends each of the tokens to appendable, separated by delimiter.

Each token will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

appendable - the object to append the results to

delimiter - a string to append between every element, but not at the beginning or end

tokens - objects to append

Returns:

the same Appendable instance that was passed in

Throws:

Join.JoinException - if an IOException occurs

join

public static <T extends Appendable> T join(T appendable,
                                            String keyValueSeparator,
                                            String entryDelimiter,
                                            Map<?,?> map)

Appends the contents of map to appendable, with entries separated by entryDelimiter, and keys and values separated with keyValueSeparator.

Each key and value will be converted to a CharSequence using String.valueOf(Object), if it isn't a CharSequence already. Note that this implies that null tokens will be appended as the four-character string "null".

Parameters:

appendable - the object to append the results to

keyValueSeparator - a string to append between every key and its associated value

entryDelimiter - a string to append between every entry, but not at the beginning or end

map - the map containing the data to join

Returns:

the same Appendable instance that was passed in