content: /*
   * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  package java.util;
  
  /**
   * {@code StringJoiner} is used to construct a sequence of characters separated
   * by a delimiter and optionally starting with a supplied prefix
   * and ending with a supplied suffix.
   * <p>
   * Prior to adding something to the {@code StringJoiner}, its
   * {@code sj.toString()} method will, by default, return {@code prefix + suffix}.
   * However, if the {@code setEmptyValue} method is called, the {@code emptyValue}
   * supplied will be returned instead. This can be used, for example, when
   * creating a string using set notation to indicate an empty set, i.e.
   * <code>"{}"</code>, where the {@code prefix} is <code>"{"</code>, the
   * {@code suffix} is <code>"}"</code> and nothing has been added to the
   * {@code StringJoiner}.
   *
   * @apiNote
   * <p>The String {@code "[George:Sally:Fred]"} may be constructed as follows:
   *
   * <pre> {@code
   * StringJoiner sj = new StringJoiner(":", "[", "]");
   * sj.add("George").add("Sally").add("Fred");
   * String desiredString = sj.toString();
   * }</pre>
   * <p>
   * A {@code StringJoiner} may be employed to create formatted output from a
   * {@link java.util.stream.Stream} using
   * {@link java.util.stream.Collectors#joining(CharSequence)}. For example:
   *
   * <pre> {@code
   * List<Integer> numbers = Arrays.asList(1, 2, 3, 4);
   * String commaSeparatedNumbers = numbers.stream()
   *     .map(i -> i.toString())
   *     .collect(Collectors.joining(", "));
   * }</pre>
   *
   * @see java.util.stream.Collectors#joining(CharSequence)
   * @see java.util.stream.Collectors#joining(CharSequence, CharSequence, CharSequence)
   * @since  1.8
  */
  public final class StringJoiner {
      private final String prefix;
      private final String delimiter;
      private final String suffix;
  
      /*
       * StringBuilder value -- at any time, the characters constructed from the
       * prefix, the added element separated by the delimiter, but without the
       * suffix, so that we can more easily add elements without having to jigger
       * the suffix each time.
       */
      private StringBuilder value;
  
      /*
       * By default, the string consisting of prefix+suffix, returned by
       * toString(), or properties of value, when no elements have yet been added,
       * i.e. when it is empty.  This may be overridden by the user to be some
       * other value including the empty String.
       */
      private String emptyValue;
  
      /**
       * Constructs a {@code StringJoiner} with no characters in it, with no
       * {@code prefix} or {@code suffix}, and a copy of the supplied
       * {@code delimiter}.
       * If no characters are added to the {@code StringJoiner} and methods
       * accessing the value of it are invoked, it will not return a
       * {@code prefix} or {@code suffix} (or properties thereof) in the result,
       * unless {@code setEmptyValue} has first been called.
       *
       * @param  delimiter the sequence of characters to be used between each
       *         element added to the {@code StringJoiner} value
       * @throws NullPointerException if {@code delimiter} is {@code null}
       */
      public StringJoiner(CharSequence delimiter) {
          this(delimiter, "", "");
      }
  
      /**
       * Constructs a {@code StringJoiner} with no characters in it using copies
       * of the supplied {@code prefix}, {@code delimiter} and {@code suffix}.
       * If no characters are added to the {@code StringJoiner} and methods
       * accessing the string value of it are invoked, it will return the
       * {@code prefix + suffix} (or properties thereof) in the result, unless
       * {@code setEmptyValue} has first been called.
       *
       * @param  delimiter the sequence of characters to be used between each
       *         element added to the {@code StringJoiner}
       * @param  prefix the sequence of characters to be used at the beginning
       * @param  suffix the sequence of characters to be used at the end
       * @throws NullPointerException if {@code prefix}, {@code delimiter}, or
       *         {@code suffix} is {@code null}
       */
      public StringJoiner(CharSequence delimiter,
                          CharSequence prefix,
                          CharSequence suffix) {
          Objects.requireNonNull(prefix, "The prefix must not be null");
          Objects.requireNonNull(delimiter, "The delimiter must not be null");
          Objects.requireNonNull(suffix, "The suffix must not be null");
          // make defensive copies of arguments
          this.prefix = prefix.toString();
          this.delimiter = delimiter.toString();
          this.suffix = suffix.toString();
          this.emptyValue = this.prefix + this.suffix;
      }
  
      /**
       * Sets the sequence of characters to be used when determining the string
       * representation of this {@code StringJoiner} and no elements have been
       * added yet, that is, when it is empty.  A copy of the {@code emptyValue}
       * parameter is made for this purpose. Note that once an add method has been
       * called, the {@code StringJoiner} is no longer considered empty, even if
       * the element(s) added correspond to the empty {@code String}.
       *
       * @param  emptyValue the characters to return as the value of an empty
       *         {@code StringJoiner}
       * @return this {@code StringJoiner} itself so the calls may be chained
       * @throws NullPointerException when the {@code emptyValue} parameter is
       *         {@code null}
       */
      public StringJoiner setEmptyValue(CharSequence emptyValue) {
          this.emptyValue = Objects.requireNonNull(emptyValue,
              "The empty value must not be null").toString();
          return this;
      }
  
      /**
       * Returns the current value, consisting of the {@code prefix}, the values
       * added so far separated by the {@code delimiter}, and the {@code suffix},
       * unless no elements have been added in which case, the
       * {@code prefix + suffix} or the {@code emptyValue} characters are returned
       *
       * @return the string representation of this {@code StringJoiner}
       */
      @Override
      public String toString() {
          if (value == null) {
              return emptyValue;
          } else {
              if (suffix.equals("")) {
                  return value.toString();
              } else {
                  int initialLength = value.length();
                  String result = value.append(suffix).toString();
                  // reset value to pre-append initialLength
                  value.setLength(initialLength);
                  return result;
              }
          }
      }
  
      /**
       * Adds a copy of the given {@code CharSequence} value as the next
       * element of the {@code StringJoiner} value. If {@code newElement} is
       * {@code null}, then {@code "null"} is added.
       *
       * @param  newElement The element to add
       * @return a reference to this {@code StringJoiner}
       */
      public StringJoiner add(CharSequence newElement) {
          prepareBuilder().append(newElement);
          return this;
      }
  
      /**
       * Adds the contents of the given {@code StringJoiner} without prefix and
       * suffix as the next element if it is non-empty. If the given {@code
       * StringJoiner} is empty, the call has no effect.
       *
       * <p>A {@code StringJoiner} is empty if {@link #add(CharSequence) add()}
       * has never been called, and if {@code merge()} has never been called
       * with a non-empty {@code StringJoiner} argument.
       *
       * <p>If the other {@code StringJoiner} is using a different delimiter,
       * then elements from the other {@code StringJoiner} are concatenated with
       * that delimiter and the result is appended to this {@code StringJoiner}
       * as a single element.
       *
       * @param other The {@code StringJoiner} whose contents should be merged
       *              into this one
       * @throws NullPointerException if the other {@code StringJoiner} is null
       * @return This {@code StringJoiner}
       */
      public StringJoiner merge(StringJoiner other) {
          Objects.requireNonNull(other);
          if (other.value != null) {
              final int length = other.value.length();
              // lock the length so that we can seize the data to be appended
              // before initiate copying to avoid interference, especially when
              // merge 'this'
              StringBuilder builder = prepareBuilder();
              builder.append(other.value, other.prefix.length(), length);
          }
          return this;
      }
  
      private StringBuilder prepareBuilder() {
          if (value != null) {
              value.append(delimiter);
          } else {
              value = new StringBuilder().append(prefix);
          }
          return value;
      }
  
      /**
       * Returns the length of the {@code String} representation
       * of this {@code StringJoiner}. Note that if
       * no add methods have been called, then the length of the {@code String}
       * representation (either {@code prefix + suffix} or {@code emptyValue})
       * will be returned. The value should be equivalent to
       * {@code toString().length()}.
       *
       * @return the length of the current value of {@code StringJoiner}
       */
      public int length() {
          // Remember that we never actually append the suffix unless we return
          // the full (present) value or some sub-string or length of it, so that
          // we can add on more if we need to.
          return (value != null ? value.length() + suffix.length() :
                  emptyValue.length());
      }
  }
  