StringJoiner.java

/*
 * 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;

/**
 * {@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
 */
// 专用工具类，作为字符串拼接器，用来拼接字符串。内部使用String[]实现。
public final class StringJoiner {
    private final String delimiter;     // 分隔符
    private final String prefix;        // 前缀
    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;  // 设定一个“空值”，可以理解为StringJoiner的默认值
    
    /**
     * 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();
    }
    
    // 将字符串s中的char存入数组chars，并返回char的数量
    private static int getChars(String s, char[] chars, int start) {
        int len = s.length();
        s.getChars(0, len, chars, start);
        return len;
    }
    
    /**
     * 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();  // 返回子串+分隔符+前缀+后缀的长度
    }
    
    /**
     * 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}
     */
    // 设定空值（可以理解为StringJoiner的默认值）
    public StringJoiner setEmptyValue(CharSequence emptyValue) {
        this.emptyValue = Objects.requireNonNull(emptyValue, "The empty value must not be null").toString();
        return this;
    }
    
    /**
     * 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
     *
     * @return This {@code StringJoiner}
     *
     * @throws NullPointerException if the other {@code StringJoiner} is null
     */
    // 合并两个拼接器中的字符串，other中的所有子串连带分隔符将作为当前拼接器的一个子串
    public StringJoiner merge(StringJoiner other) {
        Objects.requireNonNull(other);
        if(other.elts == null) {
            return this;
        }
        // 把other中所有子串连带其分隔符拼接到一起，存入other.elts[0]
        other.compactElts();
        // 将other.elts[0]添加到当前拼接器中
        return add(other.elts[0]);
    }
    
    // 把所有子串连带分隔符拼接到一起，存入elts[0]
    private void compactElts() {
        if(size>1) {
            // 定义一个大数组，足够存储所有子串和分割符
            final char[] chars = new char[len];
            int k = getChars(elts[0], chars, 0);
            int i = 1;
            do {
                k += getChars(delimiter, chars, k);
                k += getChars(elts[i], chars, k);
                elts[i] = null;
            } while(++i<size);
            size = 1;
            elts[0] = new String(chars);
        }
    }
    
    /**
     * 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 new String(chars);
    }
}