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

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender  
      private java.lang.CharSequence delimiter
      The delimiter that separates each element.
      private java.lang.CharSequence prefix
      The sequence of characters to be used at the beginning.
      private java.lang.CharSequence suffix
      The sequence of characters to be used at the end.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private AppendableJoiner​(java.lang.CharSequence prefix, java.lang.CharSequence suffix, java.lang.CharSequence delimiter, FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender)
      Constructs a new instance.

    • 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.
      (package private) static <A extends java.lang.Appendable,​T>
      A      		 joinA​(A appendable, java.lang.CharSequence prefix, java.lang.CharSequence suffix, java.lang.CharSequence delimiter, FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender, T... elements)
      Could be public in the future, in some form.
      <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.
      private static <A extends java.lang.Appendable,​T>
      A      		 joinArray​(A appendable, java.lang.CharSequence prefix, java.lang.CharSequence suffix, java.lang.CharSequence delimiter, FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender, T[] elements)  
      (package private) static <T> java.lang.StringBuilder joinI​(java.lang.StringBuilder stringBuilder, java.lang.CharSequence prefix, java.lang.CharSequence suffix, java.lang.CharSequence delimiter, FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender, java.lang.Iterable<T> elements)
      Could be public in the future, in some form.
      private static <A extends java.lang.Appendable,​T>
      A      		 joinIterable​(A appendable, java.lang.CharSequence prefix, java.lang.CharSequence suffix, java.lang.CharSequence delimiter, FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender, java.lang.Iterable<T> elements)  
      (package private) static <T> java.lang.StringBuilder joinSB​(java.lang.StringBuilder stringBuilder, java.lang.CharSequence prefix, java.lang.CharSequence suffix, java.lang.CharSequence delimiter, FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender, T... elements)
      Could be public in the future, in some form.
      private static java.lang.CharSequence nonNull​(java.lang.CharSequence value)  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • prefix

        private final java.lang.CharSequence prefix
        The sequence of characters to be used at the beginning.

      • suffix

        private final java.lang.CharSequence suffix
        The sequence of characters to be used at the end.

      • delimiter

        private final java.lang.CharSequence delimiter
        The delimiter that separates each element.

      • appender

        private final FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender

    • Constructor Detail

      • AppendableJoiner

        private AppendableJoiner​(java.lang.CharSequence prefix,
                         java.lang.CharSequence suffix,
                         java.lang.CharSequence delimiter,
                         FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender)
        Constructs a new instance.

    • 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.

      • joinA

        @SafeVarargs
static <A extends java.lang.Appendable,​T> A joinA​(A appendable,
                                                        java.lang.CharSequence prefix,
                                                        java.lang.CharSequence suffix,
                                                        java.lang.CharSequence delimiter,
                                                        FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender,
                                                        T... elements)
                                                 throws java.io.IOException
        Could be public in the future, in some form.
        Throws:
        java.io.IOException

      • joinArray

        private static <A extends java.lang.Appendable,​T> A joinArray​(A appendable,
                                                                    java.lang.CharSequence prefix,
                                                                    java.lang.CharSequence suffix,
                                                                    java.lang.CharSequence delimiter,
                                                                    FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender,
                                                                    T[] elements)
                                                             throws java.io.IOException
        Throws:
        java.io.IOException

      • joinI

        static <T> java.lang.StringBuilder joinI​(java.lang.StringBuilder stringBuilder,
                                         java.lang.CharSequence prefix,
                                         java.lang.CharSequence suffix,
                                         java.lang.CharSequence delimiter,
                                         FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender,
                                         java.lang.Iterable<T> elements)
        Could be public in the future, in some form.

      • joinIterable

        private static <A extends java.lang.Appendable,​T> A joinIterable​(A appendable,
                                                                       java.lang.CharSequence prefix,
                                                                       java.lang.CharSequence suffix,
                                                                       java.lang.CharSequence delimiter,
                                                                       FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender,
                                                                       java.lang.Iterable<T> elements)
                                                                throws java.io.IOException
        Throws:
        java.io.IOException

      • joinSB

        @SafeVarargs
static <T> java.lang.StringBuilder joinSB​(java.lang.StringBuilder stringBuilder,
                                          java.lang.CharSequence prefix,
                                          java.lang.CharSequence suffix,
                                          java.lang.CharSequence delimiter,
                                          FailableBiConsumer<java.lang.Appendable,​T,​java.io.IOException> appender,
                                          T... elements)
        Could be public in the future, in some form.

      • nonNull

        private static java.lang.CharSequence nonNull​(java.lang.CharSequence value)

      • 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