All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • org.apache.commons.lang3.AppendableJoiner Maven / Gradle / Ivy

    Go to download

    Apache Commons Lang, a package of Java utility classes for the classes that are in java.lang's hierarchy, or are considered to be so standard as to justify existence in java.lang. The code is tested using the latest revision of the JDK for supported LTS releases: 8, 11, 17 and 21 currently. See https://github.com/apache/commons-lang/blob/master/.github/workflows/maven.yml Please ensure your build environment is up-to-date and kindly report any build issues.

    There is a newer version: 3.17.0
    Show newest version
    /*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.lang3;

import java.io.IOException;
import java.util.Iterator;
import java.util.StringJoiner;
import java.util.function.Supplier;

import org.apache.commons.lang3.exception.UncheckedException;
import org.apache.commons.lang3.function.FailableBiConsumer;

/**
 * Joins an array or {@link Iterable} into an existing {@link Appendable} like a {@link StringBuilder}; with the goal for call sites to avoid creating
 * intermediary Strings. This is like {@link String#join(CharSequence, CharSequence...)}, {@link String#join(CharSequence, Iterable)}, and {@link StringJoiner}.
 * 
    
 * Keep an instance in a (static) variable for efficient joining into an {@link Appendable} or {@link 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:
 * 
    
 *
 * 
    {@code
 * // A reuseable instance
 * private static final AppendableJoiner 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 {@link CharSequence} converter, call {@link Builder#setElementAppender(FailableBiConsumer)}, for example:
 * 
    
 *
 * 
    {@code
 * private static final AppendableJoiner 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.
 * 
    
 *
 * @param  the type of elements to join.
 * @see Appendable
 * @see StringBuilder
 * @see String#join(CharSequence, CharSequence...)
 * @see String#join(CharSequence, Iterable)
 * @see StringJoiner
 * @since 3.15.0
 */
public final class AppendableJoiner {

    /**
     * Builds instances of {@link AppendableJoiner}.
     *
     * @param  the type of elements to join.
     */
    public static final class Builder implements Supplier> {

        /** The sequence of characters to be used at the beginning. */
        private CharSequence prefix;

        /** The sequence of characters to be used at the end. */
        private CharSequence suffix;

        /** The delimiter that separates each element. */
        private CharSequence delimiter;

        /** The consumer used to render each element of type {@code T} onto an {@link Appendable}. */
        private FailableBiConsumer appender;

        /**
         * Constructs a new instance.
         */
        Builder() {
            // empty
        }

        /**
         * Gets a new instance of {@link AppendableJoiner}.
         */
        @Override
        public AppendableJoiner get() {
            return new AppendableJoiner<>(prefix, suffix, delimiter, appender);
        }

        /**
         * Sets the delimiter that separates each element.
         *
         * @param delimiter The delimiter that separates each element.
         * @return this instance.
         */
        public Builder setDelimiter(final CharSequence delimiter) {
            this.delimiter = delimiter;
            return this;
        }

        /**
         * Sets the consumer used to render each element of type {@code T} onto an {@link Appendable}.
         *
         * @param appender The consumer used to render each element of type {@code T} onto an {@link Appendable}.
         * @return this instance.
         */
        public Builder setElementAppender(final FailableBiConsumer appender) {
            this.appender = appender;
            return this;
        }

        /**
         * Sets the sequence of characters to be used at the beginning.
         *
         * @param prefix The sequence of characters to be used at the beginning.
         * @return this instance.
         */
        public Builder setPrefix(final CharSequence prefix) {
            this.prefix = prefix;
            return this;
        }

        /**
         * Sets the sequence of characters to be used at the end.
         *
         * @param suffix The sequence of characters to be used at the end.
         * @return this instance.
         */
        public Builder setSuffix(final CharSequence suffix) {
            this.suffix = suffix;
            return this;
        }

    }

    /**
     * Creates a new builder.
     *
     * @param  The type of elements.
     * @return a new builder.
     */
    public static  Builder builder() {
        return new Builder<>();
    }

    /** Could be public in the future, in some form. */
    @SafeVarargs
    static  A joinA(final A appendable, final CharSequence prefix, final CharSequence suffix, final CharSequence delimiter,
            final FailableBiConsumer appender, final T... elements) throws IOException {
        return joinArray(appendable, prefix, suffix, delimiter, appender, elements);
    }

    private static  A joinArray(final A appendable, final CharSequence prefix, final CharSequence suffix, final CharSequence delimiter,
            final FailableBiConsumer appender, final T[] elements) throws IOException {
        appendable.append(prefix);
        if (elements != null) {
            if (elements.length > 0) {
                appender.accept(appendable, elements[0]);
            }
            for (int i = 1; i < elements.length; i++) {
                appendable.append(delimiter);
                appender.accept(appendable, elements[i]);
            }
        }
        appendable.append(suffix);
        return appendable;
    }

    /** Could be public in the future, in some form. */
    static  StringBuilder joinI(final StringBuilder stringBuilder, final CharSequence prefix, final CharSequence suffix, final CharSequence delimiter,
            final FailableBiConsumer appender, final Iterable elements) {
        try {
            return joinIterable(stringBuilder, prefix, suffix, delimiter, appender, elements);
        } catch (final IOException e) {
            // Cannot happen with a StringBuilder.
            throw new UncheckedException(e);
        }
    }

    private static  A joinIterable(final A appendable, final CharSequence prefix, final CharSequence suffix,
            final CharSequence delimiter, final FailableBiConsumer appender, final Iterable elements) throws IOException {
        appendable.append(prefix);
        if (elements != null) {
            final Iterator iterator = elements.iterator();
            if (iterator.hasNext()) {
                appender.accept(appendable, iterator.next());
            }
            while (iterator.hasNext()) {
                appendable.append(delimiter);
                appender.accept(appendable, iterator.next());
            }
        }
        appendable.append(suffix);
        return appendable;
    }

    /** Could be public in the future, in some form. */
    @SafeVarargs
    static  StringBuilder joinSB(final StringBuilder stringBuilder, final CharSequence prefix, final CharSequence suffix, final CharSequence delimiter,
            final FailableBiConsumer appender, final T... elements) {
        try {
            return joinArray(stringBuilder, prefix, suffix, delimiter, appender, elements);
        } catch (final IOException e) {
            // Cannot happen with a StringBuilder.
            throw new UncheckedException(e);
        }
    }

    private static CharSequence nonNull(final CharSequence value) {
        return value != null ? value : StringUtils.EMPTY;
    }

    /** The sequence of characters to be used at the beginning. */
    private final CharSequence prefix;

    /** The sequence of characters to be used at the end. */
    private final CharSequence suffix;

    /** The delimiter that separates each element. */
    private final CharSequence delimiter;

    private final FailableBiConsumer appender;

    /**
     * Constructs a new instance.
     */
    private AppendableJoiner(final CharSequence prefix, final CharSequence suffix, final CharSequence delimiter,
            final FailableBiConsumer appender) {
        this.prefix = nonNull(prefix);
        this.suffix = nonNull(suffix);
        this.delimiter = nonNull(delimiter);
        this.appender = appender != null ? appender : (a, e) -> a.append(String.valueOf(e));
    }

    /**
     * Joins stringified objects from the given Iterable into a StringBuilder.
     *
     * @param stringBuilder The target.
     * @param elements      The source.
     * @return The given StringBuilder.
     */
    public StringBuilder join(final StringBuilder stringBuilder, final Iterable elements) {
        return joinI(stringBuilder, prefix, suffix, delimiter, appender, elements);
    }

    /**
     * Joins stringified objects from the given array into a StringBuilder.
     *
     * @param stringBuilder The target.
     * @param elements      The source.
     * @return the given target StringBuilder.
     */
    public StringBuilder join(final StringBuilder stringBuilder, @SuppressWarnings("unchecked") final T... elements) {
        return joinSB(stringBuilder, prefix, suffix, delimiter, appender, elements);
    }

    /**
     * Joins stringified objects from the given Iterable into an Appendable.
     *
     * @param         the Appendable type.
     * @param appendable The target.
     * @param elements   The source.
     * @return The given StringBuilder.
     * @throws IOException If an I/O error occurs
     */
    public  A joinA(final A appendable, final Iterable elements) throws IOException {
        return joinIterable(appendable, prefix, suffix, delimiter, appender, elements);
    }

    /**
     * Joins stringified objects from the given array into an Appendable.
     *
     * @param         the Appendable type.
     * @param appendable The target.
     * @param elements   The source.
     * @return The given StringBuilder.
     * @throws IOException If an I/O error occurs
     */
    public  A joinA(final A appendable, @SuppressWarnings("unchecked") final T... elements) throws IOException {
        return joinA(appendable, prefix, suffix, delimiter, appender, elements);
    }

}
    
    
    
    

    




    
    
    © 2015 - 2025 Weber Informatics LLC | Privacy Policy