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 jdk.internal.misc.JavaLangAccess;
28 import jdk.internal.misc.SharedSecrets;
29
30 /**
31 * {@code StringJoiner} is used to construct a sequence of characters separated
32 * by a delimiter and optionally starting with a supplied prefix
33 * and ending with a supplied suffix.
34 * <p>
35 * Prior to adding something to the {@code StringJoiner}, its
36 * {@code sj.toString()} method will, by default, return {@code prefix + suffix}.
37 * However, if the {@code setEmptyValue} method is called, the {@code emptyValue}
38 * supplied will be returned instead. This can be used, for example, when
39 * creating a string using set notation to indicate an empty set, i.e.
40 * <code>"{}"</code>, where the {@code prefix} is <code>"{"</code>, the
41 * {@code suffix} is <code>"}"</code> and nothing has been added to the
42 * {@code StringJoiner}.
43 *
44 * @apiNote
45 * <p>The String {@code "[George:Sally:Fred]"} may be constructed as follows:
46 *
47 * <pre> {@code
48 * StringJoiner sj = new StringJoiner(":", "[", "]");
49 * sj.add("George").add("Sally").add("Fred");
50 * String desiredString = sj.toString();
51 * }</pre>
52 * <p>
53 * A {@code StringJoiner} may be employed to create formatted output from a
54 * {@link java.util.stream.Stream} using
55 * {@link java.util.stream.Collectors#joining(CharSequence)}. For example:
56 *
57 * <pre> {@code
58 * List<Integer> numbers = Arrays.asList(1, 2, 3, 4);
59 * String commaSeparatedNumbers = numbers.stream()
60 * .map(i -> i.toString())
61 * .collect(Collectors.joining(", "));
62 * }</pre>
63 *
64 * @see java.util.stream.Collectors#joining(CharSequence)
65 * @see java.util.stream.Collectors#joining(CharSequence, CharSequence, CharSequence)
66 * @since 1.8
67 */
68 public final class StringJoiner {
69
70 /**
71 * Initial {@link #elts} capacity.
72 */
73 public static final int INITIAL_CAPACITY = 8;
74
75 private final String prefix;
76 private final String delimiter;
77 private final String suffix;
78
79 /**
80 * Contains all the string components added so far.
81 */
82 private String[] elts;
83
84 /** The number of string components added so far. */
85 private int size;
86
87 /** Total length in chars so far, excluding prefix and suffix. */
88 private int len;
89
90 private final int psLen;
91 private final int delimLen;
92
93 private byte coder;
94
95 /**
96 * When overriden by the user to be non-null via {@link #setEmptyValue}, the
97 * string returned by toString() when no elements have yet been added.
98 * When null, prefix + suffix is used as the empty value.
99 */
100 private String emptyValue;
101
102 private static final JavaLangAccess jla = SharedSecrets.getJavaLangAccess();
103
104 /**
105 * Constructs a {@code StringJoiner} with no characters in it, with no
106 * {@code prefix} or {@code suffix}, and a copy of the supplied
107 * {@code delimiter}.
108 * If no characters are added to the {@code StringJoiner} and methods
109 * accessing the value of it are invoked, it will not return a
110 * {@code prefix} or {@code suffix} (or properties thereof) in the result,
111 * unless {@code setEmptyValue} has first been called.
112 *
113 * @param delimiter the sequence of characters to be used between each
114 * element added to the {@code StringJoiner} value
115 * @throws NullPointerException if {@code delimiter} is {@code null}
116 */
117 public StringJoiner(CharSequence delimiter) {
118 this(delimiter, "", "");
119 }
120
121 /**
122 * Constructs a {@code StringJoiner} with no characters in it using copies
123 * of the supplied {@code prefix}, {@code delimiter} and {@code suffix}.
124 * If no characters are added to the {@code StringJoiner} and methods
125 * accessing the string value of it are invoked, it will return the
126 * {@code prefix + suffix} (or properties thereof) in the result, unless
127 * {@code setEmptyValue} has first been called.
128 *
129 * @param delimiter the sequence of characters to be used between each
130 * element added to the {@code StringJoiner}
131 * @param prefix the sequence of characters to be used at the beginning
132 * @param suffix the sequence of characters to be used at the end
133 * @throws NullPointerException if {@code prefix}, {@code delimiter}, or
134 * {@code suffix} is {@code null}
135 */
136 public StringJoiner(CharSequence delimiter,
137 CharSequence prefix,
138 CharSequence suffix) {
139 Objects.requireNonNull(prefix, "The prefix must not be null");
140 Objects.requireNonNull(delimiter, "The delimiter must not be null");
141 Objects.requireNonNull(suffix, "The suffix must not be null");
142 // make defensive copies of arguments
143 this.prefix = prefix.toString();
144 this.delimiter = delimiter.toString();
145 this.suffix = suffix.toString();
146 this.elts = new String[INITIAL_CAPACITY];
147 this.coder = jla.stringInitialCoder();
148 this.psLen = this.prefix.length() + this.suffix.length();
149 this.delimLen = delimiter.length();
150 }
151
152 /**
153 * Sets the sequence of characters to be used when determining the string
154 * representation of this {@code StringJoiner} and no elements have been
155 * added yet, that is, when it is empty. A copy of the {@code emptyValue}
156 * parameter is made for this purpose. Note that once an add method has been
157 * called, the {@code StringJoiner} is no longer considered empty, even if
158 * the element(s) added correspond to the empty {@code String}.
159 *
160 * @param emptyValue the characters to return as the value of an empty
161 * {@code StringJoiner}
162 * @return this {@code StringJoiner} itself so the calls may be chained
163 * @throws NullPointerException when the {@code emptyValue} parameter is
164 * {@code null}
165 */
166 public StringJoiner setEmptyValue(CharSequence emptyValue) {
167 this.emptyValue = Objects.requireNonNull(emptyValue,
168 "The empty value must not be null").toString();
169 return this;
170 }
171
172 /**
173 * Returns the current value, consisting of the {@code prefix}, the values
174 * added so far separated by the {@code delimiter}, and the {@code suffix},
175 * unless no elements have been added in which case, the
176 * {@code prefix + suffix} or the {@code emptyValue} characters are returned.
177 *
178 * @return the string representation of this {@code StringJoiner}
179 */
180 @Override
181 public String toString() {
182 if (size == 0) {
183 return (emptyValue != null) ?
184 emptyValue :
185 prefix + suffix;
186 } else {
187 return doConcat(psLen != 0);
188 }
189 }
190
191 /**
192 * Do the actual concatenation
193 * @param full should include prefix and suffix?
194 * @return concatenated result
195 */
196 private String doConcat(boolean full) {
197 int len = this.len + (size - 1) * delimLen;
198 byte coder = this.coder;
199
200 if (full) {
201 len += psLen;
202 coder = jla.stringMixCoder(coder, prefix);
203 coder = jla.stringMixCoder(coder, suffix);
204 }
205
206 coder = jla.stringMixCoder(coder, delimiter);
207
208 byte[] dst = jla.stringStorageFor(len, coder);
209
210 int idx = 0;
211 if (full) {
212 jla.stringGetChars(prefix, dst, idx, coder);
213 idx += prefix.length();
214 }
215 jla.stringGetChars(elts[0], dst, idx, coder);
216 idx += elts[0].length();
217 for (int i = 1; i < size; i++) {
218 jla.stringGetChars(delimiter, dst, idx, coder);
219 idx += delimLen;
220 jla.stringGetChars(elts[i], dst, idx, coder);
221 idx += elts[i].length();
222 }
223 if (full) {
224 jla.stringGetChars(suffix, dst, idx, coder);
225 }
226 return jla.newStringUnsafe(dst, coder);
227 }
228
229 /**
230 * Adds a copy of the given {@code CharSequence} value as the next
231 * element of the {@code StringJoiner} value. If {@code newElement} is
232 * {@code null}, then {@code "null"} is added.
233 *
234 * @param newElement The element to add
235 * @return a reference to this {@code StringJoiner}
236 */
237 public StringJoiner add(CharSequence newElement) {
238 final String elt = String.valueOf(newElement);
239 coder = jla.stringMixCoder(coder, elt);
240 if (size == elts.length) {
241 elts = Arrays.copyOf(elts, size * 2);
242 }
243 len += elt.length();
244 elts[size++] = elt;
245 return this;
246 }
247
248 /**
249 * Adds the contents of the given {@code StringJoiner} without prefix and
250 * suffix as the next element if it is non-empty. If the given {@code
251 * StringJoiner} is empty, the call has no effect.
252 *
253 * <p>A {@code StringJoiner} is empty if {@link #add(CharSequence) add()}
254 * has never been called, and if {@code merge()} has never been called
255 * with a non-empty {@code StringJoiner} argument.
256 *
257 * <p>If the other {@code StringJoiner} is using a different delimiter,
258 * then elements from the other {@code StringJoiner} are concatenated with
259 * that delimiter and the result is appended to this {@code StringJoiner}
260 * as a single element.
261 *
262 * @param other The {@code StringJoiner} whose contents should be merged
263 * into this one
264 * @throws NullPointerException if the other {@code StringJoiner} is null
265 * @return This {@code StringJoiner}
266 */
267 public StringJoiner merge(StringJoiner other) {
268 Objects.requireNonNull(other);
269 if (other.size == 0) {
270 return this;
271 }
272 return add(other.doConcat(false));
273 }
274
275 /**
276 * Returns the length of the {@code String} representation
277 * of this {@code StringJoiner}. Note that if
278 * no add methods have been called, then the length of the {@code String}
279 * representation (either {@code prefix + suffix} or {@code emptyValue})
280 * will be returned. The value should be equivalent to
281 * {@code toString().length()}.
282 *
283 * @return the length of the current value of {@code StringJoiner}
284 */
285 public int length() {
286 return (size == 0 && emptyValue != null) ?
287 emptyValue.length() :
288 psLen + len + Math.max(0, size - 1) * delimLen;
289 }
290 }