Added in API level 24

Summary: Ctors | Methods | Inherited Methods

StringJoiner

public final class StringJoiner
extends Object

java.lang.Object
↳	java.util.StringJoiner

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.

See also:

Summary

Public constructors
`StringJoiner(CharSequence delimiter)` Constructs a `StringJoiner` with no characters in it, with no `prefix` or `suffix`, and a copy of the supplied `delimiter`.
`StringJoiner(CharSequence delimiter, CharSequence prefix, CharSequence suffix)` Constructs a `StringJoiner` with no characters in it using copies of the supplied `prefix`, `delimiter` and `suffix`.

Public methods
`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, the `prefix + suffix` or the `emptyValue` characters are returned.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

StringJoiner

Added in API level 24

public StringJoiner (CharSequence 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`	`CharSequence`: the sequence of characters to be used between each element added to the `StringJoiner` value

Throws
`NullPointerException`	if `delimiter` is `null`

StringJoiner

Added in API level 24

public StringJoiner (CharSequence delimiter, 
                CharSequence prefix, 
                CharSequence 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`	`CharSequence`: the sequence of characters to be used between each element added to the `StringJoiner`
`prefix`	`CharSequence`: the sequence of characters to be used at the beginning
`suffix`	`CharSequence`: the sequence of characters to be used at the end

Throws
`NullPointerException`	if `prefix`, `delimiter`, or `suffix` is `null`

Public methods

add

Added in API level 24

public StringJoiner add (CharSequence 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`	`CharSequence`: The element to add

Returns
`StringJoiner`	a reference to this `StringJoiner`

length

Added in API level 24

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
`int`	the length of the current value of `StringJoiner`

merge

Added in API level 24

public StringJoiner merge (StringJoiner 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() 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`	`StringJoiner`: The `StringJoiner` whose contents should be merged into this one

Returns
`StringJoiner`	This `StringJoiner`

Throws
`NullPointerException`	if the other `StringJoiner` is null

setEmptyValue

Added in API level 24

public 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. 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`	`CharSequence`: the characters to return as the value of an empty `StringJoiner`

Returns
`StringJoiner`	this `StringJoiner` itself so the calls may be chained

Throws
`NullPointerException`	when the `emptyValue` parameter is `null`

toString

Added in API level 24

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

Returns
`String`	the string representation of this `StringJoiner`