Class StringJoiner

java.lang.Object
java.util.StringJoiner
public final classStringJoinerextendsObject
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 theStringJoiner, itssj.toString() method will, by default, returnprefix + suffix. However, if thesetEmptyValue method is called, theemptyValue 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 theprefix 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();

AStringJoiner 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

    Constructors
    Constructor
    Description
    Constructs aStringJoiner with no characters in it, with noprefix orsuffix, and a copy of the supplieddelimiter.
    Constructs aStringJoiner with no characters in it using copies of the suppliedprefix,delimiter andsuffix.

  • Method Summary

    Modifier and Type
    Method
    Description
    add(CharSequence newElement)
    Adds a copy of the givenCharSequence value as the next element of theStringJoiner value.
    int
    Returns the length of theString representation of thisStringJoiner.
    Adds the contents of the givenStringJoiner without prefix and suffix as the next element if it is non-empty.
    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.
    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.

    Methods declared in class java.lang.Object

    clone,equals,finalize,getClass,hashCode,notify,notifyAll,wait,wait,wait

  • Constructor Details

    • StringJoiner

      public StringJoiner(CharSequence delimiter)
      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

      public StringJoiner(CharSequence delimiter,CharSequence prefix,CharSequence suffix)
      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 beginning
      suffix - the sequence of characters to be used at the end
      Throws:
      NullPointerException - ifprefix,delimiter, orsuffix isnull

  • Method Details

    • setEmptyValue

      public StringJoiner 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. 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:
      thisStringJoiner itself so the calls may be chained
      Throws:
      NullPointerException - when theemptyValue parameter 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 + suffix or theemptyValue characters are returned.
      Overrides:
      toString in class Object
      Returns:
      the string representation of thisStringJoiner

    • add

      public StringJoiner add(CharSequence newElement)
      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 thisStringJoiner

    • merge

      public StringJoiner merge(StringJoiner other)
      Adds the contents of the givenStringJoiner without prefix and suffix as the next element if it is non-empty. If the given StringJoiner is empty, the call has no effect.

      AStringJoiner is empty ifadd() has never been called, and ifmerge() has never been called with a non-emptyStringJoiner argument.

      If the otherStringJoiner 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:
      ThisStringJoiner
      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 ofStringJoiner