StringJoiner

class StringJoiner
kotlin.Any
   ↳ 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.
Requires API level 24 (Android 7.0, Nougat)

Summary

Public constructors
<init>(delimiter: CharSequence!)

Constructs a StringJoiner with no characters in it, with no prefix or suffix, and a copy of the supplied delimiter.

<init>(delimiter: CharSequence!, prefix: CharSequence!, suffix: CharSequence!)

Constructs a StringJoiner with no characters in it using copies of the supplied prefix, delimiter and suffix.

Public methods
StringJoiner!
add(newElement: CharSequence!)

Adds a copy of the given CharSequence value as the next element of the StringJoiner value.

Int

Returns the length of the String representation of this StringJoiner.

String

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
Requires API level 24 (Android 7.0, Nougat)

StringJoiner!

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.

StringJoiner!

Adds the contents of the given StringJoiner without prefix and suffix as the next element if it is non-empty.

Public constructors

<init>

StringJoiner(delimiter: CharSequence!)

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
Exceptions
NullPointerException if delimiter is null

<init>

StringJoiner(delimiter: CharSequence!, prefix: CharSequence!, suffix: CharSequence!)

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
Exceptions
NullPointerException if prefix, delimiter, or suffix is null

Public methods

add

added in API level 24
fun add(newElement: CharSequence!): StringJoiner!

Adds a copy of the given CharSequence value as the next element of the StringJoiner value. If newElement is null, then "null" is added.
Requires API level 24 (Android 7.0, Nougat)

Parameters
newElement CharSequence!: The element to add
Return
StringJoiner!: a reference to this StringJoiner

length

added in API level 24
fun length(): Int

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().
Requires API level 24 (Android 7.0, Nougat)

Return
Int: the length of the current value of StringJoiner

toString

added in API level 24
fun toString(): String

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
Requires API level 24 (Android 7.0, Nougat)

Return
String: the string representation of this StringJoiner

setEmptyValue

added in API level 24
fun setEmptyValue(emptyValue: CharSequence!): StringJoiner!

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.
Requires API level 24 (Android 7.0, Nougat)

Parameters
emptyValue CharSequence!: the characters to return as the value of an empty StringJoiner
Return
StringJoiner!: this StringJoiner itself so the calls may be chained
Exceptions
NullPointerException when the emptyValue parameter is null

merge

added in API level 24
fun merge(other: StringJoiner!): StringJoiner!

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.
Requires API level 24 (Android 7.0, Nougat)

Parameters
other StringJoiner!: The StringJoiner whose contents should be merged into this one
Return
StringJoiner!: This StringJoiner
Exceptions
NullPointerException if the other StringJoiner is null