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

Package org.apache.commons.lang3

# 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 java.lang.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