Class StringJoiner

java.lang.Object

java.util.StringJoiner

public final class StringJoiner
extends Object

StringJoiner is used to construct a sequence of characters separated by a delimiter and optionally starting with a supplied prefix and ending with a supplied suffix.

Prior to adding something to the StringJoiner, its sj.toString() method will, by default, return prefix + suffix. However, if the setEmptyValue method is called, the emptyValue supplied will be returned instead. This can be used, for example, when creating a string using set notation to indicate an empty set, i.e. "{}", where the prefix is "{", the suffix is "}" and nothing has been added to the StringJoiner.

API Note:

The String "[George:Sally:Fred]" may be constructed as follows:

StringJoiner sj = new StringJoiner(":", "[", "]");
sj.add("George").add("Sally").add("Fred");
String desiredString = sj.toString();

A StringJoiner may be employed to create formatted output from a Stream using Collectors.joining(CharSequence). For example:

List<Integer> numbers = Arrays.asList(1, 2, 3, 4);
String commaSeparatedNumbers = numbers.stream()
    .map(i -> i.toString())
    .collect(Collectors.joining(", "));

Since:

1.8

See Also:

• Collectors.joining(CharSequence)
• Collectors.joining(CharSequence, CharSequence, CharSequence)

Constructor Summary

Constructors

Constructor	Description
StringJoiner(CharSequence delimiter)	Constructs a StringJoiner with no characters in it, with no prefix or suffix, and a copy of the supplied delimiter.
StringJoiner(CharSequence delimiter, CharSequence prefix, CharSequence suffix)	Constructs a StringJoiner with no characters in it using copies of the supplied prefix, delimiter and suffix.

Method Summary

Modifier and Type	Method	Description
StringJoiner	add(CharSequence newElement)	Adds a copy of the given CharSequence value as the next element of the StringJoiner value.
int	length()	Returns the length of the String representation of this StringJoiner.
StringJoiner	merge(StringJoiner other)	Adds the contents of the given StringJoiner without prefix and suffix as the next element if it is non-empty.
StringJoiner	setEmptyValue(CharSequence emptyValue)	Sets the sequence of characters to be used when determining the string representation of this StringJoiner and no elements have been added yet, that is, when it is empty.
String	toString()	Returns the current value, consisting of the prefix, the values added so far separated by the delimiter, and the suffix, unless no elements have been added in which case, the prefix + suffix or the emptyValue characters are returned.

Methods declared in class Object

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

Modifier and Type	Method	Description
protected Object	clone()	Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
boolean	equals(Object o)	Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
protected void	finalize()	Deprecated, for removal: This API element is subject to removal in a future version. May cause performance issues, deadlocks and hangs.
final Class<? extends Object>	getClass()	Answers the unique instance of java.lang.Class which represents the class of the receiver.
int	hashCode()	Answers an integer hash code for the receiver.
final void	notify()	Causes one thread which is waiting on the receiver to be made ready to run.
final void	notifyAll()	Causes all threads which are waiting on the receiver to be made ready to run.
final void	wait()	Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by notify or notifyAll).
final void	wait(long time)	Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.
final void	wait(long time, int frac)	Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.

Constructor Details

StringJoiner

public StringJoiner(CharSequence delimiter)

Constructs a StringJoiner with no characters in it, with no prefix or suffix, and a copy of the supplied delimiter. If no characters are added to the StringJoiner and methods accessing the value of it are invoked, it will not return a prefix or suffix (or properties thereof) in the result, unless setEmptyValue has first been called.

Parameters:

delimiter - the sequence of characters to be used between each element added to the StringJoiner value

Throws:

NullPointerException - if delimiter is null

StringJoiner

public StringJoiner(CharSequence delimiter,
 CharSequence prefix,
 CharSequence suffix)

Constructs a StringJoiner with no characters in it using copies of the supplied prefix, delimiter and suffix. If no characters are added to the StringJoiner and methods accessing the string value of it are invoked, it will return the prefix + suffix (or properties thereof) in the result, unless setEmptyValue has first been called.

Parameters:

delimiter - the sequence of characters to be used between each element added to the StringJoiner

prefix - the sequence of characters to be used at the beginning

suffix - the sequence of characters to be used at the end

Throws:

NullPointerException - if prefix, delimiter, or suffix is null

Method Details

setEmptyValue

public StringJoiner setEmptyValue(CharSequence emptyValue)

Sets the sequence of characters to be used when determining the string representation of this StringJoiner and no elements have been added yet, that is, when it is empty. A copy of the emptyValue parameter is made for this purpose. Note that once an add method has been called, the StringJoiner is no longer considered empty, even if the element(s) added correspond to the empty String.

Parameters:

emptyValue - the characters to return as the value of an empty StringJoiner

Returns:

this StringJoiner itself so the calls may be chained

Throws:

NullPointerException - when the emptyValue parameter is null

toString

public String toString()

Returns the current value, consisting of the prefix, the values added so far separated by the delimiter, and the suffix, unless no elements have been added in which case, the prefix + suffix or the emptyValue characters are returned.

Overrides:

toString in class Object

Returns:

the string representation of this StringJoiner

add

public StringJoiner add(CharSequence newElement)

Adds a copy of the given CharSequence value as the next element of the StringJoiner value. If newElement is null, then "null" is added.

Parameters:

newElement - The element to add

Returns:

a reference to this StringJoiner

merge

public StringJoiner merge(StringJoiner other)

Adds the contents of the given StringJoiner without prefix and suffix as the next element if it is non-empty. If the given StringJoiner is empty, the call has no effect.

A StringJoiner is empty if add() has never been called, and if merge() has never been called with a non-empty StringJoiner argument.

If the other StringJoiner is using a different delimiter, then elements from the other StringJoiner are concatenated with that delimiter and the result is appended to this StringJoiner as a single element.

Parameters:

other - The StringJoiner whose contents should be merged into this one

Returns:

This StringJoiner

Throws:

NullPointerException - if the other StringJoiner is null

length

public int length()

Returns the length of the String representation of this StringJoiner. Note that if no add methods have been called, then the length of the String representation (either prefix + suffix or emptyValue) will be returned. The value should be equivalent to toString().length().

Returns:

the length of the current value of StringJoiner