AppendableJoiner

public final class org.apache.commons.lang3.AppendableJoiner<T>

Joins an array or Iterable into an existing Appendable like a StringBuilder; with the goal for call sites to avoid creating intermediary Strings. This is like String#join(CharSequence, CharSequence...), String#join(CharSequence, Iterable), and StringJoiner.

Keep an instance in a (static) variable for efficient joining into an Appendable or StringBuilder without creating temporary Strings.

Use the builder and instance methods to reuse the same kind of joining prefix, suffix, delimiter, and string conversion.

For example:

// A reusable instance
private static final AppendableJoiner<Object> JOINER = AppendableJoiner.builder()
    .setPrefix("[")
    .setSuffix("]")
    .setDelimiter(", ")
    .get();

...
// Builds straight into a StringBuilder:
StringBuilder sbuilder = new StringBuilder("1");
JOINER.join(sbuilder, "A", "B");
sbuilder.append("2");
JOINER.join(sbuilder, "C", "D");
sbuilder.append("3");
// Returns "1[A, B]2[C, D]3"
return sbuilder.toString();
}

To provide a custom Object element to CharSequence converter, call Builder#setElementAppender(FailableBiConsumer), for example:

private static final AppendableJoiner<Item> JOINER = AppendableJoiner.builder()
    .setElementAppender(e -> (a, e) -> a.append(e.getFoo())
                                       a.append(e.getBar())
                                       a.append('!'))
    ...
    .get();

}

This class is immutable and thread-safe.

Parameters:

<T> – The type of elements to join.

See also:

• Appendable

• StringBuilder

• String#join(CharSequence, CharSequence...)

• String#join(CharSequence, Iterable)

• StringJoiner

Since:

3.15.0

Methods

builder()	Creates a new builder.
join(StringBuilder, Iterable)	Joins stringified objects from the given Iterable into a StringBuilder.
join(StringBuilder, Object[])	Joins stringified objects from the given array into a StringBuilder.
joinA(Appendable, Iterable)	Joins stringified objects from the given Iterable into an Appendable.
joinA(Appendable, Object[])	Joins stringified objects from the given array into an Appendable.

public static <T> AppendableJoiner.Builder<T> builder()

Creates a new builder.

Type parameters:

<T> – The type of elements.

Returns:

A new builder.

public StringBuilder join(StringBuilder stringBuilder, Iterable<T> elements)

Joins stringified objects from the given Iterable into a StringBuilder.

Parameters:

• stringBuilder – The target.

• elements – The source.

Returns:

The given StringBuilder.

public StringBuilder join(StringBuilder stringBuilder, @SuppressWarnings({"unchecked"}) T... elements)

Joins stringified objects from the given array into a StringBuilder.

Parameters:

• stringBuilder – The target.

• elements – The source.

Returns:

The given target StringBuilder.

public <A extends Appendable> A joinA(A appendable, Iterable<T> elements) throws IOException

Joins stringified objects from the given Iterable into an Appendable.

Type parameters:

<A> – the Appendable type.

Parameters:

• appendable – The target.

• elements – The source.

Returns:

The given StringBuilder.

Throws:

java.io.IOException – Thrown if an I/O error occurs.

public <A extends Appendable> A joinA(A appendable, @SuppressWarnings({"unchecked"}) T... elements) throws IOException

Joins stringified objects from the given array into an Appendable.

Type parameters:

<A> – the Appendable type.

Parameters:

• appendable – The target.

• elements – The source.

Returns:

The given StringBuilder.

Throws:

java.io.IOException – Thrown if an I/O error occurs.