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:

  • 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