src/share/classes/java/util/StringJoiner.java

Print this page
rev 7571 : 8017231: Add StringJoiner.merge
Reviewed-by:
Contributed-by: brian.goetz@oracle.com, henry.jen@oracle.com


  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


 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      *


  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


 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      */
 206     public StringJoiner merge(StringJoiner other) {
 207         Objects.requireNonNull(other);
 208         if (other.value != null) {
 209             StringBuilder builder = prepareBuilder();
 210             StringBuilder otherBuilder = other.value;
 211             if (other.prefix.length() < otherBuilder.length()) {
 212                 builder.append(otherBuilder, other.prefix.length(), otherBuilder.length());
 213             }
 214         }
 215         return this;
 216     }
 217 
 218     private StringBuilder prepareBuilder() {
 219         if (value != null) {
 220             value.append(delimiter);
 221         } else {
 222             value = new StringBuilder().append(prefix);
 223         }
 224         return value;
 225     }
 226 
 227     /**
 228      * The length of the {@code StringJoiner} value, i.e. the length of
 229      * {@code String} representation of the {@code StringJoiner}. Note that if
 230      * no add methods have been called, then the length of the {@code String}
 231      * representation (either {@code prefix + suffix} or {@code emptyValue})
 232      * will be returned. The value should be equivalent to
 233      * {@code toString().length()}.
 234      *