269 lines
11 KiB
Java
269 lines
11 KiB
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
|
||
|
|
*/
|
||
|
|
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;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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 new String(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] = new String(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();
|
||
|
|
}
|
||
|
|
}
|