StringJoiner (Java Platform SE 8 ) (original) (raw)

• java.lang.Object

• • java.util.StringJoiner

• ---

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, itssj.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 "{", thesuffix is "}" 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 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:
Collectors.joining(CharSequence), Collectors.joining(CharSequence, CharSequence, CharSequence)

• • Constructor Summary

  Constructors

  Constructor	Description
  StringJoiner(CharSequence delimiter)	Constructs a StringJoiner with no characters in it, with noprefix or suffix, and a copy of the supplieddelimiter.
  StringJoiner(CharSequence delimiter,CharSequence prefix,CharSequence suffix)	Constructs a StringJoiner with no characters in it using copies of the supplied prefix, delimiter and suffix.

  • Method Summary

  All Methods Instance Methods Concrete Methods

  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, theprefix + suffix or the emptyValue characters are returned

     * ### Methods inherited from class java.lang.[Object](../../java/lang/Object.html "class in java.lang")  
     `[clone](../../java/lang/Object.html#clone--), [equals](../../java/lang/Object.html#equals-java.lang.Object-), [finalize](../../java/lang/Object.html#finalize--), [getClass](../../java/lang/Object.html#getClass--), [hashCode](../../java/lang/Object.html#hashCode--), [notify](../../java/lang/Object.html#notify--), [notifyAll](../../java/lang/Object.html#notifyAll--), [wait](../../java/lang/Object.html#wait--), [wait](../../java/lang/Object.html#wait-long-), [wait](../../java/lang/Object.html#wait-long-int-)`

• • Constructor Detail

     * #### StringJoiner  
     public StringJoiner([CharSequence](../../java/lang/CharSequence.html "interface in java.lang") delimiter)  
     Constructs a `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.  
     Parameters:  
     `delimiter` \- the sequence of characters to be used between each element added to the `StringJoiner` value  
     Throws:  
     `[NullPointerException](../../java/lang/NullPointerException.html "class in java.lang")` \- if `delimiter` is `null`  
     * #### StringJoiner  
     public StringJoiner([CharSequence](../../java/lang/CharSequence.html "interface in java.lang") delimiter,  
                         [CharSequence](../../java/lang/CharSequence.html "interface in java.lang") prefix,  
                         [CharSequence](../../java/lang/CharSequence.html "interface in java.lang") suffix)  
     Constructs a `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.  
     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](../../java/lang/NullPointerException.html "class in java.lang")` \- if `prefix`, `delimiter`, or`suffix` is `null`  

  • Method Detail

    * #### setEmptyValue  
    public [StringJoiner](../../java/util/StringJoiner.html "class in java.util") setEmptyValue([CharSequence](../../java/lang/CharSequence.html "interface in java.lang") 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. 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`.  
    Parameters:  
    `emptyValue` \- the characters to return as the value of an empty`StringJoiner`  
    Returns:  
    this `StringJoiner` itself so the calls may be chained  
    Throws:  
    `[NullPointerException](../../java/lang/NullPointerException.html "class in java.lang")` \- when the `emptyValue` parameter is`null`  
    * #### toString  
    public [String](../../java/lang/String.html "class in java.lang") 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  
    Overrides:  
    `[toString](../../java/lang/Object.html#toString--)` in class `[Object](../../java/lang/Object.html "class in java.lang")`  
    Returns:  
    the string representation of this `StringJoiner`  
    * #### add  
    public [StringJoiner](../../java/util/StringJoiner.html "class in java.util") add([CharSequence](../../java/lang/CharSequence.html "interface in java.lang") newElement)  
    Adds a copy of the given `CharSequence` value as the next element of the `StringJoiner` value. If `newElement` is`null`, then `"null"` is added.  
    Parameters:  
    `newElement` \- The element to add  
    Returns:  
    a reference to this `StringJoiner`  
    * #### merge  
    public [StringJoiner](../../java/util/StringJoiner.html "class in java.util") merge([StringJoiner](../../java/util/StringJoiner.html "class in java.util") other)  
    Adds the contents of the given `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()](../../java/util/StringJoiner.html#add-java.lang.CharSequence-) 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.  
    Parameters:  
    `other` \- The `StringJoiner` whose contents should be merged into this one  
    Returns:  
    This `StringJoiner`  
    Throws:  
    `[NullPointerException](../../java/lang/NullPointerException.html "class in java.lang")` \- if the other `StringJoiner` is null  
    * #### length  
    public int length()  
    Returns the length of the `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()`.  
    Returns:  
    the length of the current value of `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.