Package org.apache.commons.lang3

Class AppendableJoiner<T>

  • Type Parameters:
    T - the type of elements to join.
    public final class AppendableJoiner<T>
extends java.lang.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

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> AppendableJoiner.Builder<T> builder()
      Creates a new builder.
      java.lang.StringBuilder join​(java.lang.StringBuilder stringBuilder, java.lang.Iterable<T> elements)
      Joins stringified objects from the given Iterable into a StringBuilder.
      java.lang.StringBuilder join​(java.lang.StringBuilder stringBuilder, T... elements)
      Joins stringified objects from the given array into a StringBuilder.
      <A extends java.lang.Appendable>
      A      		 joinA​(A appendable, java.lang.Iterable<T> elements)
      Joins stringified objects from the given Iterable into an Appendable.
      <A extends java.lang.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 Detail

      • 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 java.lang.StringBuilder join​(java.lang.StringBuilder stringBuilder,
                                    java.lang.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 java.lang.StringBuilder join​(java.lang.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 java.lang.Appendable> A joinA​(A appendable,
                                                java.lang.Iterable<T> elements)
                                         throws java.io.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 - If an I/O error occurs

      • joinA

        public <A extends java.lang.Appendable> A joinA​(A appendable,
                                                T... elements)
                                         throws java.io.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 - If an I/O error occurs