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.
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(", "));
Collectors.joining(CharSequence),
Collectors.joining(CharSequence, CharSequence, CharSequence)| 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. |
| 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 |
public StringJoiner(CharSequence delimiter)
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.delimiter - the sequence of characters to be used between each
element added to the StringJoiner valueNullPointerException - if delimiter is nullpublic StringJoiner(CharSequence delimiter, CharSequence prefix, CharSequence suffix)
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.delimiter - the sequence of characters to be used between each
element added to the StringJoinerprefix - the sequence of characters to be used at the beginningsuffix - the sequence of characters to be used at the endNullPointerException - if prefix, delimiter, or
suffix is nullpublic StringJoiner setEmptyValue(CharSequence emptyValue)
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.emptyValue - the characters to return as the value of an empty
StringJoinerStringJoiner itself so the calls may be chainedNullPointerException - when the emptyValue parameter is
nullpublic String toString()
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 returnedpublic StringJoiner add(CharSequence newElement)
CharSequence value as the next
element of the StringJoiner value. If newElement is
null, then "null" is added.newElement - The element to addStringJoinerpublic StringJoiner merge(StringJoiner other)
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.
other - The StringJoiner whose contents should be merged
into this oneStringJoinerNullPointerException - if the other StringJoiner is nullpublic int length()
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().StringJoiner Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2025, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.