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 given {@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 given {@code StringJoiner} without prefix and
 190      * suffix as the next element if it is non-empty. If the given {@code
 191      * 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      * then elements from the other {@code StringJoiner} are concatenated with
 199      * that delimiter and the result is appended to this {@code StringJoiner}
 200      * as a 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      * @return This {@code StringJoiner}
 206      */
 207     public StringJoiner merge(StringJoiner other) {
 208         Objects.requireNonNull(other);
 209         if (other.value != null) {
 210             StringBuilder builder = prepareBuilder();
 211             StringBuilder otherBuilder = other.value;
 212             if (other.prefix.length() < otherBuilder.length()) {
 213                 builder.append(otherBuilder, other.prefix.length(), otherBuilder.length());
 214             }
 215         }
 216         return this;
 217     }
 218 
 219     private StringBuilder prepareBuilder() {
 220         if (value != null) {
 221             value.append(delimiter);
 222         } else {
 223             value = new StringBuilder().append(prefix);
 224         }
 225         return value;
 226     }
 227 
 228     /**
 229      * The length of the {@code StringJoiner} value, i.e. the length of
 230      * {@code String} representation of the {@code StringJoiner}. Note that if
 231      * no add methods have been called, then the length of the {@code String}
 232      * representation (either {@code prefix + suffix} or {@code emptyValue})
 233      * will be returned. The value should be equivalent to
 234      * {@code toString().length()}.
 235      *
 236      * @return the length of the current value of {@code StringJoiner}
 237      */
 238     public int length() {
 239         // Remember that we never actually append the suffix unless we return
 240         // the full (present) value or some sub-string or length of it, so that
 241         // we can add on more if we need to.
 242         return (value != null ? value.length() + suffix.length() :
 243                 emptyValue.length());
 244     }
 245 }