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#joining(CharSequence)}. 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.joining(", "));
59  * }</pre>
60  *
61  * @see java.util.stream.Collectors#joining(CharSequence)
62  * @see java.util.stream.Collectors#joining(CharSequence, CharSequence, CharSequence)
63  * @since  1.8
64 */
65 public final class StringJoiner {
66     private final String prefix;
67     private final String delimiter;
68     private final String suffix;
69 
70     /*
71      * StringBuilder value -- at any time, the characters constructed from the
72      * prefix, the added element separated by the delimiter, but without the
73      * suffix, so that we can more easily add elements without having to jigger
74      * the suffix each time.
75      */
76     private StringBuilder value;
77 
78     /*
79      * By default, the string consisting of prefix+suffix, returned by
80      * toString(), or properties of value, when no elements have yet been added,
81      * i.e. when it is empty.  This may be overridden by the user to be some
82      * other value including the empty String.
83      */
84     private String emptyValue;
85 
86     /**
87      * Constructs a {@code StringJoiner} with no characters in it, with no
88      * {@code prefix} or {@code suffix}, and a copy of the supplied
89      * {@code delimiter}.
90      * If no characters are added to the {@code StringJoiner} and methods
91      * accessing the value of it are invoked, it will not return a
92      * {@code prefix} or {@code suffix} (or properties thereof) in the result,
93      * unless {@code setEmptyValue} has first been called.
94      *
95      * @param  delimiter the sequence of characters to be used between each
96      *         element added to the {@code StringJoiner} value
97      * @throws NullPointerException if {@code delimiter} is {@code null}
98      */
StringJoiner(CharSequence delimiter)99     public StringJoiner(CharSequence delimiter) {
100         this(delimiter, "", "");
101     }
102 
103     /**
104      * Constructs a {@code StringJoiner} with no characters in it using copies
105      * of the supplied {@code prefix}, {@code delimiter} and {@code suffix}.
106      * If no characters are added to the {@code StringJoiner} and methods
107      * accessing the string value of it are invoked, it will return the
108      * {@code prefix + suffix} (or properties thereof) in the result, unless
109      * {@code setEmptyValue} has first been called.
110      *
111      * @param  delimiter the sequence of characters to be used between each
112      *         element added to the {@code StringJoiner}
113      * @param  prefix the sequence of characters to be used at the beginning
114      * @param  suffix the sequence of characters to be used at the end
115      * @throws NullPointerException if {@code prefix}, {@code delimiter}, or
116      *         {@code suffix} is {@code null}
117      */
StringJoiner(CharSequence delimiter, CharSequence prefix, CharSequence suffix)118     public StringJoiner(CharSequence delimiter,
119                         CharSequence prefix,
120                         CharSequence suffix) {
121         Objects.requireNonNull(prefix, "The prefix must not be null");
122         Objects.requireNonNull(delimiter, "The delimiter must not be null");
123         Objects.requireNonNull(suffix, "The suffix must not be null");
124         // make defensive copies of arguments
125         this.prefix = prefix.toString();
126         this.delimiter = delimiter.toString();
127         this.suffix = suffix.toString();
128         this.emptyValue = this.prefix + this.suffix;
129     }
130 
131     /**
132      * Sets the sequence of characters to be used when determining the string
133      * representation of this {@code StringJoiner} and no elements have been
134      * added yet, that is, when it is empty.  A copy of the {@code emptyValue}
135      * parameter is made for this purpose. Note that once an add method has been
136      * called, the {@code StringJoiner} is no longer considered empty, even if
137      * the element(s) added correspond to the empty {@code String}.
138      *
139      * @param  emptyValue the characters to return as the value of an empty
140      *         {@code StringJoiner}
141      * @return this {@code StringJoiner} itself so the calls may be chained
142      * @throws NullPointerException when the {@code emptyValue} parameter is
143      *         {@code null}
144      */
setEmptyValue(CharSequence emptyValue)145     public StringJoiner setEmptyValue(CharSequence emptyValue) {
146         this.emptyValue = Objects.requireNonNull(emptyValue,
147             "The empty value must not be null").toString();
148         return this;
149     }
150 
151     /**
152      * Returns the current value, consisting of the {@code prefix}, the values
153      * added so far separated by the {@code delimiter}, and the {@code suffix},
154      * unless no elements have been added in which case, the
155      * {@code prefix + suffix} or the {@code emptyValue} characters are returned
156      *
157      * @return the string representation of this {@code StringJoiner}
158      */
159     @Override
toString()160     public String toString() {
161         if (value == null) {
162             return emptyValue;
163         } else {
164             if (suffix.equals("")) {
165                 return value.toString();
166             } else {
167                 int initialLength = value.length();
168                 String result = value.append(suffix).toString();
169                 // reset value to pre-append initialLength
170                 value.setLength(initialLength);
171                 return result;
172             }
173         }
174     }
175 
176     /**
177      * Adds a copy of the given {@code CharSequence} value as the next
178      * element of the {@code StringJoiner} value. If {@code newElement} is
179      * {@code null}, then {@code "null"} is added.
180      *
181      * @param  newElement The element to add
182      * @return a reference to this {@code StringJoiner}
183      */
add(CharSequence newElement)184     public StringJoiner add(CharSequence newElement) {
185         prepareBuilder().append(newElement);
186         return this;
187     }
188 
189     /**
190      * Adds the contents of the given {@code StringJoiner} without prefix and
191      * suffix as the next element if it is non-empty. If the given {@code
192      * StringJoiner} is empty, the call has no effect.
193      *
194      * <p>A {@code StringJoiner} is empty if {@link #add(CharSequence) add()}
195      * has never been called, and if {@code merge()} has never been called
196      * with a non-empty {@code StringJoiner} argument.
197      *
198      * <p>If the other {@code StringJoiner} is using a different delimiter,
199      * then elements from the other {@code StringJoiner} are concatenated with
200      * that delimiter and the result is appended to this {@code StringJoiner}
201      * as a single element.
202      *
203      * @param other The {@code StringJoiner} whose contents should be merged
204      *              into this one
205      * @throws NullPointerException if the other {@code StringJoiner} is null
206      * @return This {@code StringJoiner}
207      */
merge(StringJoiner other)208     public StringJoiner merge(StringJoiner other) {
209         Objects.requireNonNull(other);
210         if (other.value != null) {
211             final int length = other.value.length();
212             // lock the length so that we can seize the data to be appended
213             // before initiate copying to avoid interference, especially when
214             // merge 'this'
215             StringBuilder builder = prepareBuilder();
216             builder.append(other.value, other.prefix.length(), length);
217         }
218         return this;
219     }
220 
prepareBuilder()221     private StringBuilder prepareBuilder() {
222         if (value != null) {
223             value.append(delimiter);
224         } else {
225             value = new StringBuilder().append(prefix);
226         }
227         return value;
228     }
229 
230     /**
231      * Returns the length of the {@code String} representation
232      * of this {@code StringJoiner}. Note that if
233      * no add methods have been called, then the length of the {@code String}
234      * representation (either {@code prefix + suffix} or {@code emptyValue})
235      * will be returned. The value should be equivalent to
236      * {@code toString().length()}.
237      *
238      * @return the length of the current value of {@code StringJoiner}
239      */
length()240     public int length() {
241         // Remember that we never actually append the suffix unless we return
242         // the full (present) value or some sub-string or length of it, so that
243         // we can add on more if we need to.
244         return (value != null ? value.length() + suffix.length() :
245                 emptyValue.length());
246     }
247 }
248