/*

 * Copyright (c) 2013, 2014, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.util;

import sun.misc.JavaLangAccess;

import sun.misc.SharedSecrets;

/**

 * {@code StringJoiner} is used to construct a sequence of characters separated

 * by a delimiter and optionally starting with a supplied prefix

 * and ending with a supplied suffix.

 * <p>

 * Prior to adding something to the {@code StringJoiner}, its

 * {@code sj.toString()} method will, by default, return {@code prefix + suffix}.

 * However, if the {@code setEmptyValue} method is called, the {@code emptyValue}

 * supplied will be returned instead. This can be used, for example, when

 * creating a string using set notation to indicate an empty set, i.e.

 * <code>"{}"</code>, where the {@code prefix} is <code>"{"</code>, the

 * {@code suffix} is <code>"}"</code> and nothing has been added to the

 * {@code StringJoiner}.

 *

 * @apiNote

 * <p>The String {@code "[George:Sally:Fred]"} may be constructed as follows:

 *

 * <pre> {@code

 * StringJoiner sj = new StringJoiner(":", "[", "]");

 * sj.add("George").add("Sally").add("Fred");

 * String desiredString = sj.toString();

 * }</pre>

 * <p>

 * A {@code StringJoiner} may be employed to create formatted output from a

 * {@link java.util.stream.Stream} using

 * {@link java.util.stream.Collectors#joining(CharSequence)}. For example:

 *

 * <pre> {@code

 * List<Integer> numbers = Arrays.asList(1, 2, 3, 4);

 * String commaSeparatedNumbers = numbers.stream()

 *     .map(i -> i.toString())

 *     .collect(Collectors.joining(", "));

 * }</pre>

 *

 * @see java.util.stream.Collectors#joining(CharSequence)

 * @see java.util.stream.Collectors#joining(CharSequence, CharSequence, CharSequence)

 * @since  1.8

*/

public final class StringJoiner {

    private final String prefix;

    private final String delimiter;

    private final String suffix;

    /** Contains all the string components added so far. */

    private String[] elts;

    /** The number of string components added so far. */

    private int size;

    /** Total length in chars so far, excluding prefix and suffix. */

    private int len;

    /**

     * When overriden by the user to be non-null via {@link setEmptyValue}, the

     * string returned by toString() when no elements have yet been added.

     * When null, prefix + suffix is used as the empty value.

     */

    private String emptyValue;

    private static final JavaLangAccess jla = SharedSecrets.getJavaLangAccess();

    /**

     * Constructs a {@code StringJoiner} with no characters in it, with no

     * {@code prefix} or {@code suffix}, and a copy of the supplied

     * {@code delimiter}.

     * If no characters are added to the {@code StringJoiner} and methods

     * accessing the value of it are invoked, it will not return a

     * {@code prefix} or {@code suffix} (or properties thereof) in the result,

     * unless {@code setEmptyValue} has first been called.

     *

     * @param  delimiter the sequence of characters to be used between each

     *         element added to the {@code StringJoiner} value

     * @throws NullPointerException if {@code delimiter} is {@code null}

     */

    public StringJoiner(CharSequence delimiter) {

        this(delimiter, "", "");

    }

    /**

     * Constructs a {@code StringJoiner} with no characters in it using copies

     * of the supplied {@code prefix}, {@code delimiter} and {@code suffix}.

     * If no characters are added to the {@code StringJoiner} and methods

     * accessing the string value of it are invoked, it will return the

     * {@code prefix + suffix} (or properties thereof) in the result, unless

     * {@code setEmptyValue} has first been called.

     *

     * @param  delimiter the sequence of characters to be used between each

     *         element added to the {@code StringJoiner}

     * @param  prefix the sequence of characters to be used at the beginning

     * @param  suffix the sequence of characters to be used at the end

     * @throws NullPointerException if {@code prefix}, {@code delimiter}, or

     *         {@code suffix} is {@code null}

     */

    public StringJoiner(CharSequence delimiter,

                        CharSequence prefix,

                        CharSequence suffix) {

        Objects.requireNonNull(prefix, "The prefix must not be null");

        Objects.requireNonNull(delimiter, "The delimiter must not be null");

        Objects.requireNonNull(suffix, "The suffix must not be null");

        // make defensive copies of arguments

        this.prefix = prefix.toString();

        this.delimiter = delimiter.toString();

        this.suffix = suffix.toString();

    }

    /**

     * Sets the sequence of characters to be used when determining the string

     * representation of this {@code StringJoiner} and no elements have been

     * added yet, that is, when it is empty.  A copy of the {@code emptyValue}

     * parameter is made for this purpose. Note that once an add method has been

     * called, the {@code StringJoiner} is no longer considered empty, even if

     * the element(s) added correspond to the empty {@code String}.

     *

     * @param  emptyValue the characters to return as the value of an empty

     *         {@code StringJoiner}

     * @return this {@code StringJoiner} itself so the calls may be chained

     * @throws NullPointerException when the {@code emptyValue} parameter is

     *         {@code null}

     */

    public StringJoiner setEmptyValue(CharSequence emptyValue) {

        this.emptyValue = Objects.requireNonNull(emptyValue,

            "The empty value must not be null").toString();

        return this;

    }

    private static int getChars(String s, char[] chars, int start) {

        int len = s.length();

        s.getChars(0, len, chars, start);

        return len;

    }

    /**

     * Returns the current value, consisting of the {@code prefix}, the values

     * added so far separated by the {@code delimiter}, and the {@code suffix},

     * unless no elements have been added in which case, the

     * {@code prefix + suffix} or the {@code emptyValue} characters are returned.

     *

     * @return the string representation of this {@code StringJoiner}

     */

    @Override

    public String toString() {

        final String[] elts = this.elts;

        if (elts == null && emptyValue != null) {

            return emptyValue;

        }

        final int size = this.size;

        final int addLen = prefix.length() + suffix.length();

        if (addLen == 0) {

            compactElts();

            return size == 0 ? "" : elts[0];

        }

        final String delimiter = this.delimiter;

        final char[] chars = new char[len + addLen];

        int k = getChars(prefix, chars, 0);

        if (size > 0) {

            k += getChars(elts[0], chars, k);

            for (int i = 1; i < size; i++) {

                k += getChars(delimiter, chars, k);

                k += getChars(elts[i], chars, k);

            }

        }

        k += getChars(suffix, chars, k);

        return jla.newStringUnsafe(chars);

    }

    /**

     * Adds a copy of the given {@code CharSequence} value as the next

     * element of the {@code StringJoiner} value. If {@code newElement} is

     * {@code null}, then {@code "null"} is added.

     *

     * @param  newElement The element to add

     * @return a reference to this {@code StringJoiner}

     */

    public StringJoiner add(CharSequence newElement) {

        final String elt = String.valueOf(newElement);

        if (elts == null) {

            elts = new String[8];

        } else {

            if (size == elts.length)

                elts = Arrays.copyOf(elts, 2 * size);

            len += delimiter.length();

        }

        len += elt.length();

        elts[size++] = elt;

        return this;

    }

    /**

     * Adds the contents of the given {@code StringJoiner} without prefix and

     * suffix as the next element if it is non-empty. If the given {@code

     * StringJoiner} is empty, the call has no effect.

     *

     * <p>A {@code StringJoiner} is empty if {@link #add(CharSequence) add()}

     * has never been called, and if {@code merge()} has never been called

     * with a non-empty {@code StringJoiner} argument.

     *

     * <p>If the other {@code StringJoiner} is using a different delimiter,

     * then elements from the other {@code StringJoiner} are concatenated with

     * that delimiter and the result is appended to this {@code StringJoiner}

     * as a single element.

     *

     * @param other The {@code StringJoiner} whose contents should be merged

     *              into this one

     * @throws NullPointerException if the other {@code StringJoiner} is null

     * @return This {@code StringJoiner}

     */

    public StringJoiner merge(StringJoiner other) {

        Objects.requireNonNull(other);

        if (other.elts == null) {

            return this;

        }

        other.compactElts();

        return add(other.elts[0]);

    }

    private void compactElts() {

        if (size > 1) {

            final char[] chars = new char[len];

            int i = 1, k = getChars(elts[0], chars, 0);

            do {

                k += getChars(delimiter, chars, k);

                k += getChars(elts[i], chars, k);

                elts[i] = null;

            } while (++i < size);

            size = 1;

            elts[0] = jla.newStringUnsafe(chars);

        }

    }

    /**

     * Returns the length of the {@code String} representation

     * of this {@code StringJoiner}. Note that if

     * no add methods have been called, then the length of the {@code String}

     * representation (either {@code prefix + suffix} or {@code emptyValue})

     * will be returned. The value should be equivalent to

     * {@code toString().length()}.

     *

     * @return the length of the current value of {@code StringJoiner}

     */

    public int length() {

        return (size == 0 && emptyValue != null) ? emptyValue.length() :

            len + prefix.length() + suffix.length();

    }

}