- java.lang.Object
- 
- java.util.StringJoiner
 
- 
 public final class StringJoiner extends Object StringJoineris 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, itssj.toString()method will, by default, returnprefix + suffix. However, if thesetEmptyValuemethod is called, theemptyValuesupplied 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 theprefixis"{", thesuffixis"}"and nothing has been added to theStringJoiner.- 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 - StringJoinermay be employed to create formatted output from a- Streamusing- 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 SummaryConstructors Constructor Description StringJoiner(CharSequence delimiter)Constructs aStringJoinerwith no characters in it, with noprefixorsuffix, and a copy of the supplieddelimiter.StringJoiner(CharSequence delimiter, CharSequence prefix, CharSequence suffix)Constructs aStringJoinerwith no characters in it using copies of the suppliedprefix,delimiterandsuffix.
 - 
Method SummaryAll Methods Instance Methods Concrete Methods Modifier and Type Method Description StringJoineradd(CharSequence newElement)Adds a copy of the givenCharSequencevalue as the next element of theStringJoinervalue.intlength()Returns the length of theStringrepresentation of thisStringJoiner.StringJoinermerge(StringJoiner other)Adds the contents of the givenStringJoinerwithout prefix and suffix as the next element if it is non-empty.StringJoinersetEmptyValue(CharSequence emptyValue)Sets the sequence of characters to be used when determining the string representation of thisStringJoinerand no elements have been added yet, that is, when it is empty.StringtoString()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 + suffixor theemptyValuecharacters are returned.
 
- 
- 
- 
Constructor Detail- 
StringJoinerpublic StringJoiner(CharSequence delimiter) Constructs aStringJoinerwith no characters in it, with noprefixorsuffix, and a copy of the supplieddelimiter. If no characters are added to theStringJoinerand methods accessing the value of it are invoked, it will not return aprefixorsuffix(or properties thereof) in the result, unlesssetEmptyValuehas first been called.- Parameters:
- delimiter- the sequence of characters to be used between each element added to the- StringJoinervalue
- Throws:
- NullPointerException- if- delimiteris- null
 
 - 
StringJoinerpublic StringJoiner(CharSequence delimiter, CharSequence prefix, CharSequence suffix) Constructs aStringJoinerwith no characters in it using copies of the suppliedprefix,delimiterandsuffix. If no characters are added to theStringJoinerand methods accessing the string value of it are invoked, it will return theprefix + suffix(or properties thereof) in the result, unlesssetEmptyValuehas 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- suffixis- null
 
 
- 
 - 
Method Detail- 
setEmptyValuepublic StringJoiner setEmptyValue(CharSequence emptyValue) Sets the sequence of characters to be used when determining the string representation of thisStringJoinerand no elements have been added yet, that is, when it is empty. A copy of theemptyValueparameter is made for this purpose. Note that once an add method has been called, theStringJoineris 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 empty- StringJoiner
- Returns:
- this StringJoineritself so the calls may be chained
- Throws:
- NullPointerException- when the- emptyValueparameter is- null
 
 - 
toStringpublic String 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 + suffixor theemptyValuecharacters are returned.
 - 
addpublic StringJoiner add(CharSequence newElement) Adds a copy of the givenCharSequencevalue as the next element of theStringJoinervalue. IfnewElementisnull, then"null"is added.- Parameters:
- newElement- The element to add
- Returns:
- a reference to this StringJoiner
 
 - 
mergepublic StringJoiner merge(StringJoiner other) Adds the contents of the givenStringJoinerwithout prefix and suffix as the next element if it is non-empty. If the givenStringJoineris empty, the call has no effect.A StringJoineris empty ifadd()has never been called, and ifmerge()has never been called with a non-emptyStringJoinerargument.If the other StringJoineris using a different delimiter, then elements from the otherStringJoinerare concatenated with that delimiter and the result is appended to thisStringJoineras a single element.- Parameters:
- other- The- StringJoinerwhose contents should be merged into this one
- Returns:
- This StringJoiner
- Throws:
- NullPointerException- if the other- StringJoineris null
 
 - 
lengthpublic int length() Returns the length of theStringrepresentation of thisStringJoiner. Note that if no add methods have been called, then the length of theStringrepresentation (eitherprefix + suffixoremptyValue) will be returned. The value should be equivalent totoString().length().- Returns:
- the length of the current value of StringJoiner
 
 
- 
 
-