Class StringJoiner
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 aStream
usingCollectors.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:
-
Constructor Summary
ConstructorDescriptionStringJoiner
(CharSequence delimiter) Constructs aStringJoiner
with no characters in it, with noprefix
orsuffix
, and a copy of the supplieddelimiter
.StringJoiner
(CharSequence delimiter, CharSequence prefix, CharSequence suffix) Constructs aStringJoiner
with no characters in it using copies of the suppliedprefix
,delimiter
andsuffix
. -
Method Summary
Modifier and TypeMethodDescriptionadd
(CharSequence newElement) Adds a copy of the givenCharSequence
value as the next element of theStringJoiner
value.int
length()
Returns the length of theString
representation of thisStringJoiner
.merge
(StringJoiner other) Adds the contents of the givenStringJoiner
without prefix and suffix as the next element if it is non-empty.setEmptyValue
(CharSequence emptyValue) Sets the sequence of characters to be used when determining the string representation of thisStringJoiner
and no elements have been added yet, that is, when it is empty.toString()
Returns the current value, consisting of theprefix
, the values added so far separated by thedelimiter
, and thesuffix
, unless no elements have been added in which case, theprefix + suffix
or theemptyValue
characters are returned.
-
Constructor Details
-
StringJoiner
Constructs aStringJoiner
with no characters in it, with noprefix
orsuffix
, and a copy of the supplieddelimiter
. If no characters are added to theStringJoiner
and methods accessing the value of it are invoked, it will not return aprefix
orsuffix
(or properties thereof) in the result, unlesssetEmptyValue
has first been called.- Parameters:
delimiter
- the sequence of characters to be used between each element added to theStringJoiner
value- Throws:
NullPointerException
- ifdelimiter
isnull
-
StringJoiner
Constructs aStringJoiner
with no characters in it using copies of the suppliedprefix
,delimiter
andsuffix
. If no characters are added to theStringJoiner
and methods accessing the string value of it are invoked, it will return theprefix + suffix
(or properties thereof) in the result, unlesssetEmptyValue
has first been called.- Parameters:
delimiter
- the sequence of characters to be used between each element added to theStringJoiner
prefix
- the sequence of characters to be used at the beginningsuffix
- the sequence of characters to be used at the end- Throws:
NullPointerException
- ifprefix
,delimiter
, orsuffix
isnull
-
-
Method Details
-
setEmptyValue
Sets the sequence of characters to be used when determining the string representation of thisStringJoiner
and no elements have been added yet, that is, when it is empty. A copy of theemptyValue
parameter is made for this purpose. Note that once an add method has been called, theStringJoiner
is no longer considered empty, even if the element(s) added correspond to the emptyString
.- Parameters:
emptyValue
- the characters to return as the value of an emptyStringJoiner
- Returns:
- this
StringJoiner
itself so the calls may be chained - Throws:
NullPointerException
- when theemptyValue
parameter isnull
-
toString
Returns the current value, consisting of theprefix
, the values added so far separated by thedelimiter
, and thesuffix
, unless no elements have been added in which case, theprefix + suffix
or theemptyValue
characters are returned. -
add
Adds a copy of the givenCharSequence
value as the next element of theStringJoiner
value. IfnewElement
isnull
, then"null"
is added.- Parameters:
newElement
- The element to add- Returns:
- a reference to this
StringJoiner
-
merge
Adds the contents of the givenStringJoiner
without prefix and suffix as the next element if it is non-empty. If the givenStringJoiner
is empty, the call has no effect.A
StringJoiner
is empty ifadd()
has never been called, and ifmerge()
has never been called with a non-emptyStringJoiner
argument.If the other
StringJoiner
is using a different delimiter, then elements from the otherStringJoiner
are concatenated with that delimiter and the result is appended to thisStringJoiner
as a single element.- Parameters:
other
- TheStringJoiner
whose contents should be merged into this one- Returns:
- This
StringJoiner
- Throws:
NullPointerException
- if the otherStringJoiner
is null
-
length
public int length()Returns the length of theString
representation of thisStringJoiner
. Note that if no add methods have been called, then the length of theString
representation (eitherprefix + suffix
oremptyValue
) will be returned. The value should be equivalent totoString().length()
.- Returns:
- the length of the current value of
StringJoiner
-