AppendableJoiner (Apache Commons Lang 3.20.0 API)
Description: declaration: package: org.apache.commons.lang3, class: AppendableJoiner

# Class AppendableJoiner<T>

java.lang.Object
org.apache.commons.lang3.AppendableJoiner<T>

Type Parameters:
  `T` - the type of elements to join.

public final class AppendableJoiner<T> extends Object
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 reuseable 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 `AppendableJoiner.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.

Since:
  3.15.0
See Also:
  - `Appendable`
  - `StringBuilder`
  - `String.join(CharSequence, CharSequence...)`
  - `String.join(CharSequence, Iterable)`
  - `StringJoiner`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `AppendableJoiner.Builder<T>`
  Builds instances of `AppendableJoiner`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> AppendableJoiner.Builder<T>`
  `builder()`
  Creates a new builder.
  `StringBuilder`
  `join(StringBuilder stringBuilder, Iterable<T> elements)`
  Joins stringified objects from the given Iterable into a StringBuilder.
  `StringBuilder`
  `join(StringBuilder stringBuilder, T... elements)`
  Joins stringified objects from the given array into a StringBuilder.
  `<A extends Appendable>
  A`
  `joinA(A appendable, Iterable<T> elements)`
  Joins stringified objects from the given Iterable into an Appendable.
  `<A extends Appendable>
  A`
  `joinA(A appendable, T... elements)`
  Joins stringified objects from the given array into an Appendable.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### builder

    public static <T> AppendableJoiner.Builder<T> builder()
    Creates a new builder.
    Type Parameters:
      `T` - The type of elements.
    Returns:
      a new builder.

  - ### join

    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.

  - ### join

    public StringBuilder join(StringBuilder stringBuilder, T... elements)
    Joins stringified objects from the given array into a StringBuilder.
    Parameters:
      `stringBuilder` - The target.
      `elements` - The source.
    Returns:
      the given target StringBuilder.

  - ### joinA

    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:
      `IOException` - If an I/O error occurs

  - ### joinA

    public <A extends Appendable> A joinA(A appendable, 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:
      `IOException` - If an I/O error occurs