1 /*
2 * Copyright (c) 2013, 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 /**
28 * {@code StringJoiner} is used to construct a sequence of characters separated
29 * by a delimiter and optionally starting with a supplied prefix
30 * and ending with a supplied suffix.
31 * <p>
32 * Prior to adding something to the {@code StringJoiner}, its
33 * {@code sj.toString()} method will, by default, return {@code prefix + suffix}.
34 * However, if the {@code setEmptyValue} method is called, the {@code emptyValue}
35 * supplied will be returned instead. This can be used, for example, when
36 * creating a string using set notation to indicate an empty set, i.e.
37 * <code>"{}"</code>, where the {@code prefix} is <code>"{"</code>, the
38 * {@code suffix} is <code>"}"</code> and nothing has been added to the
39 * {@code StringJoiner}.
40 *
41 * @apiNote
42 * <p>The String {@code "[George:Sally:Fred]"} may be constructed as follows:
43 *
44 * <pre> {@code
45 * StringJoiner sj = new StringJoiner(":", "[", "]");
46 * sj.add("George").add("Sally").add("Fred");
47 * String desiredString = sj.toString();
48 * }</pre>
49 * <p>
50 * A {@code StringJoiner} may be employed to create formatted output from a
51 * {@link java.util.stream.Stream} using
52 * {@link java.util.stream.Collectors#toStringJoiner}. For example:
53 *
54 * <pre> {@code
55 * List<Integer> numbers = Arrays.asList(1, 2, 3, 4);
56 * String commaSeparatedNumbers = numbers.stream()
57 * .map(i -> i.toString())
58 * .collect(Collectors.toStringJoiner(", ")).toString();
59 * }</pre>
60 *
61 * @see java.util.stream.Collectors#toStringJoiner
62 * @since 1.8
63 */
64 public final class StringJoiner {
65 private final String prefix;
66 private final String delimiter;
67 private final String suffix;
68
69 /*
70 * StringBuilder value -- at any time, the characters constructed from the
71 * prefix, the added element separated by the delimiter, but without the
72 * suffix, so that we can more easily add elements without having to jigger
73 * the suffix each time.
74 */
75 private StringBuilder value;
76
77 /*
78 * By default, the string consisting of prefix+suffix, returned by
79 * toString(), or properties of value, when no elements have yet been added,
80 * i.e. when it is empty. This may be overridden by the user to be some
81 * other value including the empty String.
82 */
83 private String emptyValue;
84
85 /**
86 * Constructs a {@code StringJoiner} with no characters in it, with no
87 * {@code prefix} or {@code suffix}, and a copy of the supplied
88 * {@code delimiter}.
89 * If no characters are added to the {@code StringJoiner} and methods
90 * accessing the value of it are invoked, it will not return a
91 * {@code prefix} or {@code suffix} (or properties thereof) in the result,
92 * unless {@code setEmptyValue} has first been called.
93 *
94 * @param delimiter the sequence of characters to be used between each
95 * element added to the {@code StringJoiner} value
96 * @throws NullPointerException if {@code delimiter} is {@code null}
97 */
98 public StringJoiner(CharSequence delimiter) {
99 this(delimiter, "", "");
100 }
101
102 /**
103 * Constructs a {@code StringJoiner} with no characters in it using copies
104 * of the supplied {@code prefix}, {@code delimiter} and {@code suffix}.
105 * If no characters are added to the {@code StringJoiner} and methods
106 * accessing the string value of it are invoked, it will return the
107 * {@code prefix + suffix} (or properties thereof) in the result, unless
108 * {@code setEmptyValue} has first been called.
109 *
110 * @param delimiter the sequence of characters to be used between each
111 * element added to the {@code StringJoiner}
112 * @param prefix the sequence of characters to be used at the beginning
113 * @param suffix the sequence of characters to be used at the end
114 * @throws NullPointerException if {@code prefix}, {@code delimiter}, or
115 * {@code suffix} is {@code null}
116 */
117 public StringJoiner(CharSequence delimiter, CharSequence prefix,
118 CharSequence suffix) {
119 Objects.requireNonNull(prefix, "The prefix must not be null");
120 Objects.requireNonNull(delimiter, "The delimiter must not be null");
121 Objects.requireNonNull(suffix, "The suffix must not be null");
122 // make defensive copies of arguments
123 this.prefix = prefix.toString();
124 this.delimiter = delimiter.toString();
125 this.suffix = suffix.toString();
126 this.emptyValue = this.prefix + this.suffix;
127 }
128
129 /**
130 * Sets the sequence of characters to be used when determining the string
131 * representation of this {@code StringJoiner} and no elements have been
132 * added yet, i.e. when it is empty. A copy of the {@code emptyValue}
133 * parameter is made for this purpose. Note that once an add method has been
134 * called, the {@code StringJoiner} is no longer considered empty, even if
135 * the element(s) added correspond to the empty {@code String}.
136 *
137 * @param emptyValue the characters to return as the value of an empty
138 * {@code StringJoiner}
139 * @return this {@code StringJoiner} itself so the calls may be chained
140 * @throws NullPointerException when the {@code emptyValue} parameter is
141 * {@code null}
142 */
143 public StringJoiner setEmptyValue(CharSequence emptyValue) {
144 this.emptyValue = Objects.requireNonNull(emptyValue,
145 "The empty value must not be null").toString();
146 return this;
147 }
148
149 /**
150 * Returns the current value, consisting of the {@code prefix}, the values
151 * added so far separated by the {@code delimiter}, and the {@code suffix},
152 * unless no elements have been added in which case, the
153 * {@code prefix + suffix} or the {@code emptyValue} characters are returned
154 *
155 * @return the string representation of this {@code StringJoiner}
156 */
157 @Override
158 public String toString() {
159 if (value == null) {
160 return emptyValue;
161 } else {
162 if (suffix.equals("")) {
163 return value.toString();
164 } else {
165 int initialLength = value.length();
166 String result = value.append(suffix).toString();
167 // reset value to pre-append initialLength
168 value.setLength(initialLength);
169 return result;
170 }
171 }
172 }
173
174 /**
175 * Add the a copy of the supplied {@code CharSequence} value as the next
176 * element of the {@code StringJoiner} value. If {@code newElement} is
177 * {@code null}, then {@code "null"} is added.
178 *
179 * @param newElement The element to add
180 * @return a reference to this {@code StringJoiner}
181 */
182 public StringJoiner add(CharSequence newElement) {
183 prepareBuilder().append(newElement);
184 return this;
185 }
186
187 private StringBuilder prepareBuilder() {
188 if (value != null) {
189 value.append(delimiter);
190 } else {
191 value = new StringBuilder().append(prefix);
192 }
193 return value;
194 }
195
196 /**
197 * The length of the {@code StringJoiner} value, i.e. the length of
198 * {@code String} representation of the {@code StringJoiner}. Note that if
199 * no add methods have been called, then the length of the {@code String}
200 * representation (either {@code prefix + suffix} or {@code emptyValue})
201 * will be returned. The value should be equivalent to
202 * {@code toString().length()}.
203 *
204 * @return the length of the current value of {@code StringJoiner}
205 */
206 public int length() {
207 // Remember that we never actually append the suffix unless we return
208 // the full (present) value or some sub-string or length of it, so that
209 // we can add on more if we need to.
210 return (value != null ? value.length() + suffix.length() :
211 emptyValue.length());
212 }
213 }