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, 118 CharSequence prefix, 119 CharSequence suffix) { 120 Objects.requireNonNull(prefix, "The prefix must not be null"); 121 Objects.requireNonNull(delimiter, "The delimiter must not be null"); 122 Objects.requireNonNull(suffix, "The suffix must not be null"); 123 // make defensive copies of arguments 124 this.prefix = prefix.toString(); 125 this.delimiter = delimiter.toString(); 126 this.suffix = suffix.toString(); 127 this.emptyValue = this.prefix + this.suffix; 128 } 129 130 /** 131 * Sets the sequence of characters to be used when determining the string 132 * representation of this {@code StringJoiner} and no elements have been 133 * added yet, i.e. when it is empty. A copy of the {@code emptyValue} 134 * parameter is made for this purpose. Note that once an add method has been 135 * called, the {@code StringJoiner} is no longer considered empty, even if 136 * the element(s) added correspond to the empty {@code String}. 137 * 138 * @param emptyValue the characters to return as the value of an empty 139 * {@code StringJoiner} 140 * @return this {@code StringJoiner} itself so the calls may be chained 141 * @throws NullPointerException when the {@code emptyValue} parameter is 142 * {@code null} 143 */ 144 public StringJoiner setEmptyValue(CharSequence emptyValue) { 145 this.emptyValue = Objects.requireNonNull(emptyValue, 146 "The empty value must not be null").toString(); 147 return this; 148 } 149 150 /** 151 * Returns the current value, consisting of the {@code prefix}, the values 152 * added so far separated by the {@code delimiter}, and the {@code suffix}, 153 * unless no elements have been added in which case, the 154 * {@code prefix + suffix} or the {@code emptyValue} characters are returned 155 * 156 * @return the string representation of this {@code StringJoiner} 157 */ 158 @Override 159 public String toString() { 160 if (value == null) { 161 return emptyValue; 162 } else { 163 if (suffix.equals("")) { 164 return value.toString(); 165 } else { 166 int initialLength = value.length(); 167 String result = value.append(suffix).toString(); 168 // reset value to pre-append initialLength 169 value.setLength(initialLength); 170 return result; 171 } 172 } 173 } 174 175 /** 176 * Adds a copy of the supplied {@code CharSequence} value as the next 177 * element of the {@code StringJoiner} value. If {@code newElement} is 178 * {@code null}, then {@code "null"} is added. 179 * 180 * @param newElement The element to add 181 * @return a reference to this {@code StringJoiner} 182 */ 183 public StringJoiner add(CharSequence newElement) { 184 prepareBuilder().append(newElement); 185 return this; 186 } 187 188 /** 189 * Adds the contents of the supplied {@code StringJoiner} without prefix 190 * and suffix as the next element if it is nonempty. If the supplied 191 * {@code StringJoiner} is empty, the call has no effect. 192 * 193 * <p>A {@code StringJoiner} is empty if {@link add(CharSequence) add()} 194 * has never been called, and if {@code merge()} has never been called 195 * with a non- empty {@code StringJoiner} argument. 196 * 197 * <p>If the other {@code StringJoiner} is using a different delimiter, 198 * elements from the other {@code StringJoiner} are concatenated with that 199 * delimiter and the result is appended to this {@code StringJoiner} as a 200 * single element. 201 * 202 * @param other The {@code StringJoiner} whose contents should be merged 203 * into this one 204 * @throws NullPointerException if the other {@code StringJoiner} is null 205 */ 206 public StringJoiner merge(StringJoiner other) { 207 Objects.requireNonNull(other); 208 if (other.value != null) { 209 StringBuilder builder = prepareBuilder(); 210 StringBuilder otherBuffer = other.value; 211 for (int i=other.prefix.length(); i < otherBuffer.length(); i++) 212 builder.append(otherBuffer.charAt(i)); 213 } 214 return this; 215 } 216 217 private StringBuilder prepareBuilder() { 218 if (value != null) { 219 value.append(delimiter); 220 } else { 221 value = new StringBuilder().append(prefix); 222 } 223 return value; 224 } 225 226 /** 227 * The length of the {@code StringJoiner} value, i.e. the length of 228 * {@code String} representation of the {@code StringJoiner}. Note that if 229 * no add methods have been called, then the length of the {@code String} 230 * representation (either {@code prefix + suffix} or {@code emptyValue}) 231 * will be returned. The value should be equivalent to 232 * {@code toString().length()}. 233 * 234 * @return the length of the current value of {@code StringJoiner} 235 */ 236 public int length() { 237 // Remember that we never actually append the suffix unless we return 238 // the full (present) value or some sub-string or length of it, so that 239 // we can add on more if we need to. 240 return (value != null ? value.length() + suffix.length() : 241 emptyValue.length()); 242 } 243 }