- 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 aStreamusingCollectors.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 Summary
Constructors 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 Summary
All 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
-
StringJoiner
public 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 theStringJoinervalue- Throws:
NullPointerException- ifdelimiterisnull
-
StringJoiner
public 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 theStringJoinerprefix- the sequence of characters to be used at the beginningsuffix- the sequence of characters to be used at the end- Throws:
NullPointerException- ifprefix,delimiter, orsuffixisnull
-
-
Method Detail
-
setEmptyValue
public 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 emptyStringJoiner- Returns:
- this
StringJoineritself so the calls may be chained - Throws:
NullPointerException- when theemptyValueparameter isnull
-
toString
public 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.
-
add
public 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
-
merge
public 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- TheStringJoinerwhose contents should be merged into this one- Returns:
- This
StringJoiner - Throws:
NullPointerException- if the otherStringJoineris null
-
length
public 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
-
-