/*
* Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
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;
/*
* StringBuilder value -- at any time, the characters constructed from the
* prefix, the added element separated by the delimiter, but without the
* suffix, so that we can more easily add elements without having to jigger
* the suffix each time.
*/
private
StringBuilder value;
/*
* By default, the string consisting of prefix+suffix, returned by
* toString(), or properties of value, when no elements have yet been added,
* i.e. when it is empty. This may be overridden by the user to be some
* other value including the empty String.
*/
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();
this.
emptyValue = this.
prefix + this.
suffix;
}
/**
* 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;
}
/**
* 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() {
if (
value == null) {
return
emptyValue;
} else {
if (
suffix.
equals("")) {
return
value.
toString();
} else {
int
initialLength =
value.
length();
String result =
value.
append(
suffix).
toString();
// reset value to pre-append initialLength
value.
setLength(
initialLength);
return
result;
}
}
}
/**
* 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) {
prepareBuilder().
append(
newElement);
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.
value != null) {
final int
length =
other.
value.
length();
// lock the length so that we can seize the data to be appended
// before initiate copying to avoid interference, especially when
// merge 'this'
StringBuilder builder =
prepareBuilder();
builder.
append(
other.
value,
other.
prefix.
length(),
length);
}
return this;
}
private
StringBuilder prepareBuilder() {
if (
value != null) {
value.
append(
delimiter);
} else {
value = new
StringBuilder().
append(
prefix);
}
return
value;
}
/**
* 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() {
// Remember that we never actually append the suffix unless we return
// the full (present) value or some sub-string or length of it, so that
// we can add on more if we need to.
return (
value != null ?
value.
length() +
suffix.
length() :
emptyValue.
length());
}
}