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 - 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:
- 
Constructor SummaryConstructorsConstructorDescriptionStringJoiner(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 SummaryModifier and TypeMethodDescriptionadd(CharSequence newElement) Adds a copy of the givenCharSequencevalue as the next element of theStringJoinervalue.intlength()Returns the length of theStringrepresentation of thisStringJoiner.merge(StringJoiner other) Adds the contents of the givenStringJoinerwithout 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 thisStringJoinerand 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 + suffixor theemptyValuecharacters are returned.
- 
Constructor Details- 
StringJoinerConstructs 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
 
- 
StringJoinerConstructs 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 Details- 
setEmptyValueSets 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
 
- 
toStringReturns 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.
- 
addAdds 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
 
- 
mergeAdds 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
 
 
-