1 /*
2 * Copyright (c) 2013, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.util;
26
27 import sun.misc.ConstantLengthCharSequence;
28 import sun.misc.JavaLangAccess;
29 import sun.misc.SharedSecrets;
30
31 /**
32 * {@code StringJoiner} is used to construct a sequence of characters separated
33 * by a delimiter and optionally starting with a supplied prefix
34 * and ending with a supplied suffix.
35 * <p>
36 * Prior to adding something to the {@code StringJoiner}, its
37 * {@code sj.toString()} method will, by default, return {@code prefix + suffix}.
38 * However, if the {@code setEmptyValue} method is called, the {@code emptyValue}
39 * supplied will be returned instead. This can be used, for example, when
40 * creating a string using set notation to indicate an empty set, i.e.
41 * <code>"{}"</code>, where the {@code prefix} is <code>"{"</code>, the
42 * {@code suffix} is <code>"}"</code> and nothing has been added to the
43 * {@code StringJoiner}.
44 *
45 * @apiNote
46 * <p>The String {@code "[George:Sally:Fred]"} may be constructed as follows:
47 *
48 * <pre> {@code
49 * StringJoiner sj = new StringJoiner(":", "[", "]");
50 * sj.add("George").add("Sally").add("Fred");
51 * String desiredString = sj.toString();
52 * }</pre>
53 * <p>
54 * A {@code StringJoiner} may be employed to create formatted output from a
55 * {@link java.util.stream.Stream} using
56 * {@link java.util.stream.Collectors#joining(CharSequence)}. For example:
57 *
58 * <pre> {@code
59 * List<Integer> numbers = Arrays.asList(1, 2, 3, 4);
60 * String commaSeparatedNumbers = numbers.stream()
61 * .map(i -> i.toString())
62 * .collect(Collectors.joining(", "));
63 * }</pre>
64 *
65 * @see java.util.stream.Collectors#joining(CharSequence)
66 * @see java.util.stream.Collectors#joining(CharSequence, CharSequence, CharSequence)
67 * @since 1.8
68 */
69 public final class StringJoiner {
70 private final String prefix;
71 private final String delimiter;
72 private final String suffix;
73
74 /** Contains all the components added so far. */
75 private ConstantLengthCharSequence[] elts;
76
77 /** The number of components added so far. */
78 private int size;
79
80 /** Total length in chars so far, excluding prefix and suffix. */
81 private int len;
82
83 /**
84 * When overriden by the user to be non-null via {@link setEmptyValue}, the
85 * string returned by toString() when no elements have yet been added.
86 * When null, prefix + suffix is used as the empty value.
87 */
88 private String emptyValue;
89
90 private static final JavaLangAccess jla = SharedSecrets.getJavaLangAccess();
91
92 /**
93 * Constructs a {@code StringJoiner} with no characters in it, with no
94 * {@code prefix} or {@code suffix}, and a copy of the supplied
95 * {@code delimiter}.
96 * If no characters are added to the {@code StringJoiner} and methods
97 * accessing the value of it are invoked, it will not return a
98 * {@code prefix} or {@code suffix} (or properties thereof) in the result,
99 * unless {@code setEmptyValue} has first been called.
100 *
101 * @param delimiter the sequence of characters to be used between each
102 * element added to the {@code StringJoiner} value
103 * @throws NullPointerException if {@code delimiter} is {@code null}
104 */
105 public StringJoiner(CharSequence delimiter) {
106 this(delimiter, "", "");
107 }
108
109 /**
110 * Constructs a {@code StringJoiner} with no characters in it using copies
111 * of the supplied {@code prefix}, {@code delimiter} and {@code suffix}.
112 * If no characters are added to the {@code StringJoiner} and methods
113 * accessing the string value of it are invoked, it will return the
114 * {@code prefix + suffix} (or properties thereof) in the result, unless
115 * {@code setEmptyValue} has first been called.
116 *
117 * @param delimiter the sequence of characters to be used between each
118 * element added to the {@code StringJoiner}
119 * @param prefix the sequence of characters to be used at the beginning
120 * @param suffix the sequence of characters to be used at the end
121 * @throws NullPointerException if {@code prefix}, {@code delimiter}, or
122 * {@code suffix} is {@code null}
123 */
124 public StringJoiner(CharSequence delimiter,
125 CharSequence prefix,
126 CharSequence suffix) {
127 Objects.requireNonNull(prefix, "The prefix must not be null");
128 Objects.requireNonNull(delimiter, "The delimiter must not be null");
129 Objects.requireNonNull(suffix, "The suffix must not be null");
130 // make defensive copies of arguments
131 this.prefix = prefix.toString();
132 this.delimiter = delimiter.toString();
133 this.suffix = suffix.toString();
134 }
135
136 /**
137 * Sets the sequence of characters to be used when determining the string
138 * representation of this {@code StringJoiner} and no elements have been
139 * added yet, that is, when it is empty. A copy of the {@code emptyValue}
140 * parameter is made for this purpose. Note that once an add method has been
141 * called, the {@code StringJoiner} is no longer considered empty, even if
142 * the element(s) added correspond to the empty {@code String}.
143 *
144 * @param emptyValue the characters to return as the value of an empty
145 * {@code StringJoiner}
146 * @return this {@code StringJoiner} itself so the calls may be chained
147 * @throws NullPointerException when the {@code emptyValue} parameter is
148 * {@code null}
149 */
150 public StringJoiner setEmptyValue(CharSequence emptyValue) {
151 this.emptyValue = Objects.requireNonNull(emptyValue,
152 "The empty value must not be null").toString();
153 return this;
154 }
155
156 private static int getChars(ConstantLengthCharSequence ccs,
157 char[] chars, int start) {
158 int len = ccs.length();
159 ccs.getChars(0, len, chars, start);
160 return len;
161 }
162
163 /**
164 * Returns the current value, consisting of the {@code prefix}, the values
165 * added so far separated by the {@code delimiter}, and the {@code suffix},
166 * unless no elements have been added in which case, the
167 * {@code prefix + suffix} or the {@code emptyValue} characters are returned.
168 *
169 * @return the string representation of this {@code StringJoiner}
170 */
171 @Override
172 public String toString() {
173 final ConstantLengthCharSequence[] elts = this.elts;
174 if (elts == null && emptyValue != null) {
175 return emptyValue;
176 }
177 final int size = this.size;
178 final int addLen = prefix.length() + suffix.length();
179 if (addLen == 0) {
180 compactElts();
181 return size == 0 ? "" : elts[0].toString();
182 }
183 final String delimiter = this.delimiter;
184 final char[] chars = new char[len + addLen];
185 int k = getChars(prefix, chars, 0);
186 if (size > 0) {
187 k += getChars(elts[0], chars, k);
188 for (int i = 1; i < size; i++) {
189 k += getChars(delimiter, chars, k);
190 k += getChars(elts[i], chars, k);
191 }
192 }
193 k += getChars(suffix, chars, k);
194 return jla.newStringUnsafe(chars);
195 }
196
197 /**
198 * Adds a copy of the given {@code CharSequence} value as the next
199 * element of the {@code StringJoiner} value. If {@code newElement} is
200 * {@code null}, then {@code "null"} is added.
201 *
202 * @param newElement The element to add
203 * @return a reference to this {@code StringJoiner}
204 */
205 public StringJoiner add(CharSequence newElement) {
206 final ConstantLengthCharSequence elt =
207 ConstantLengthCharSequence.valueFor(newElement);
208 if (elts == null) {
209 elts = new ConstantLengthCharSequence[8];
210 } else {
211 if (size == elts.length)
212 elts = Arrays.copyOf(elts, 2 * size);
213 len += delimiter.length();
214 }
215 len += elt.length();
216 elts[size++] = elt;
217 return this;
218 }
219
220 /**
221 * Adds the contents of the given {@code StringJoiner} without prefix and
222 * suffix as the next element if it is non-empty. If the given {@code
223 * StringJoiner} is empty, the call has no effect.
224 *
225 * <p>A {@code StringJoiner} is empty if {@link #add(CharSequence) add()}
226 * has never been called, and if {@code merge()} has never been called
227 * with a non-empty {@code StringJoiner} argument.
228 *
229 * <p>If the other {@code StringJoiner} is using a different delimiter,
230 * then elements from the other {@code StringJoiner} are concatenated with
231 * that delimiter and the result is appended to this {@code StringJoiner}
232 * as a single element.
233 *
234 * @param other The {@code StringJoiner} whose contents should be merged
235 * into this one
236 * @throws NullPointerException if the other {@code StringJoiner} is null
237 * @return This {@code StringJoiner}
238 */
239 public StringJoiner merge(StringJoiner other) {
240 Objects.requireNonNull(other);
241 if (other.elts == null) {
242 return this;
243 }
244 other.compactElts();
245 return add(other.elts[0]);
246 }
247
248 private void compactElts() {
249 if (size > 1) {
250 final char[] chars = new char[len];
251 int i = 1, k = getChars(elts[0], chars, 0);
252 do {
253 k += getChars(delimiter, chars, k);
254 k += getChars(elts[i], chars, k);
255 elts[i] = null;
256 } while (++i < size);
257 size = 1;
258 elts[0] = jla.newStringUnsafe(chars);
259 }
260 }
261
262 /**
263 * Returns the length of the {@code String} representation
264 * of this {@code StringJoiner}. Note that if
265 * no add methods have been called, then the length of the {@code String}
266 * representation (either {@code prefix + suffix} or {@code emptyValue})
267 * will be returned. The value should be equivalent to
268 * {@code toString().length()}.
269 *
270 * @return the length of the current value of {@code StringJoiner}
271 */
272 public int length() {
273 return (size == 0 && emptyValue != null) ? emptyValue.length() :
274 len + prefix.length() + suffix.length();
275 }
276 }