OpenJDK 1.22 · java.util.StringJoiner · APIdia, the JavaDoc alternative

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 java.util.stream.Stream using java.util.stream.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(", "));

Field Summary

Modifier and Type	Field and Description
private final String	delimiter
private String[]	elts Contains all the string components added so far.
private static final String[]	EMPTY_STRING_ARRAY
private String	emptyValue When overridden by the user to be non-null via `setEmptyValue(CharSequence)`, the string returned by toString() when no elements have yet been added.
private static final JavaLangAccess	JLA
private int	len Total length in chars so far, excluding prefix and suffix.
private final String	prefix
private int	size The number of string components added so far.
private final String	suffix

Constructor Summary

Access	Constructor and Description
public	StringJoiner(CharSequence the sequence of characters to be used between each element added to the `StringJoiner` value delimiter) Constructs a `StringJoiner` with no characters in it, with no `prefix` or `suffix`, and a copy of the supplied `delimiter`.
public	StringJoiner(CharSequence the sequence of characters to be used between each element added to the `StringJoiner` delimiter, CharSequence the sequence of characters to be used at the beginning prefix, CharSequence the sequence of characters to be used at the end suffix) Constructs a `StringJoiner` with no characters in it using copies of the supplied `prefix`, `delimiter` and `suffix`.

Method Summary

Modifier and Type	Method and Description
public StringJoiner	Returns: a reference to this `StringJoiner` add(CharSequence The element to add newElement) Adds a copy of the given `CharSequence` value as the next element of the `StringJoiner` value.
private int	checkAddLength(int oldLen, int inc)
private void	compactElts()
public int	Returns: the length of the current value of `StringJoiner` length() Returns the length of the `String` representation of this `StringJoiner`.
public StringJoiner	Returns: This `StringJoiner` merge(StringJoiner The `StringJoiner` whose contents should be merged into this one other) Adds the contents of the given `StringJoiner` without prefix and suffix as the next element if it is non-empty.
public StringJoiner	Returns: this `StringJoiner` itself so the calls may be chained setEmptyValue(CharSequence the characters to return as the value of an empty `StringJoiner` 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.
public String	Returns: the string representation of this `StringJoiner` toString() Overrides java.lang.Object.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.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

delimiter	back to summary
private final String delimiter

elts	back to summary
private String[] elts Contains all the string components added so far.

EMPTY_STRING_ARRAY	back to summary
private static final String[] EMPTY_STRING_ARRAY

emptyValue	back to summary
private String emptyValue When overridden by the user to be non-null via `setEmptyValue(CharSequence)`, the string returned by toString() when no elements have yet been added. When null, prefix + suffix is used as the empty value.

JLA	back to summary
private static final JavaLangAccess JLA

len	back to summary
private int len Total length in chars so far, excluding prefix and suffix.

prefix	back to summary
private final String prefix

size	back to summary
private int size The number of string components added so far.

suffix	back to summary
private final String suffix

Constructor Detail

StringJoiner back to summary

StringJoiner	back to summary
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:CharSequence the sequence of characters to be used between each element added to the `StringJoiner` value Exceptions NullPointerException: if `delimiter` is `null`

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:CharSequence: the sequence of characters to be used between each element added to the StringJoiner value

Exceptions

NullPointerException:: if delimiter is null

StringJoiner back to summary

StringJoiner	back to summary
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:CharSequence the sequence of characters to be used between each element added to the `StringJoiner` prefix:CharSequence the sequence of characters to be used at the beginning suffix:CharSequence the sequence of characters to be used at the end Exceptions NullPointerException: if `prefix`, `delimiter`, or `suffix` is `null`

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:CharSequence: the sequence of characters to be used between each element added to the StringJoiner
prefix:CharSequence: the sequence of characters to be used at the beginning
suffix:CharSequence: the sequence of characters to be used at the end

Exceptions

NullPointerException:: if prefix, delimiter, or suffix is null

Method Detail

add back to summary

add	back to summary
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:CharSequence The element to add Returns:StringJoiner a reference to this `StringJoiner`

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:CharSequence: The element to add

Returns:StringJoiner

a reference to this StringJoiner

checkAddLength	back to summary
private int checkAddLength(int oldLen, int inc)

compactElts	back to summary
private void compactElts()

length back to summary

length	back to summary
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:int the length of the current value of `StringJoiner`

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:int: the length of the current value of StringJoiner

merge back to summary

merge	back to summary
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:StringJoiner The `StringJoiner` whose contents should be merged into this one Returns:StringJoiner This `StringJoiner` Exceptions NullPointerException: if the other `StringJoiner` is null

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:StringJoiner: The StringJoiner whose contents should be merged into this one

Returns:StringJoiner

This StringJoiner

Exceptions

NullPointerException:: if the other StringJoiner is null

setEmptyValue back to summary

setEmptyValue	back to summary
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:CharSequence the characters to return as the value of an empty `StringJoiner` Returns:StringJoiner this `StringJoiner` itself so the calls may be chained Exceptions NullPointerException: when the `emptyValue` parameter is `null`

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:CharSequence: the characters to return as the value of an empty StringJoiner

Returns:StringJoiner

this StringJoiner itself so the calls may be chained

Exceptions

NullPointerException:: when the emptyValue parameter is null

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.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. Returns:String the string representation of this `StringJoiner` Annotations @Override

public String toString()

Overrides java.lang.Object.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.

Returns:String

the string representation of this StringJoiner

Annotations

@Override

public final Class StringJoiner

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail