001/*
002 * Copyright (C) 2008 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.base;
016
017import static com.google.common.base.Preconditions.checkNotNull;
018import static java.util.Objects.requireNonNull;
019
020import com.google.common.annotations.GwtCompatible;
021import com.google.errorprone.annotations.CanIgnoreReturnValue;
022import java.io.IOException;
023import java.util.AbstractList;
024import java.util.Arrays;
025import java.util.Iterator;
026import java.util.List;
027import java.util.Map;
028import java.util.Map.Entry;
029import javax.annotation.CheckForNull;
030import org.checkerframework.checker.nullness.qual.Nullable;
031
032/**
033 * An object which joins pieces of text (specified as an array, {@link Iterable}, varargs or even a
034 * {@link Map}) with a separator. It either appends the results to an {@link Appendable} or returns
035 * them as a {@link String}. Example:
036 *
037 * <pre>{@code
038 * Joiner joiner = Joiner.on("; ").skipNulls();
039 *  . . .
040 * return joiner.join("Harry", null, "Ron", "Hermione");
041 * }</pre>
042 *
043 * <p>This returns the string {@code "Harry; Ron; Hermione"}. Note that all input elements are
044 * converted to strings using {@link Object#toString()} before being appended.
045 *
046 * <p>If neither {@link #skipNulls()} nor {@link #useForNull(String)} is specified, the joining
047 * methods will throw {@link NullPointerException} if any given element is null.
048 *
049 * <p><b>Warning: joiner instances are always immutable</b>; a configuration method such as {@code
050 * useForNull} has no effect on the instance it is invoked on! You must store and use the new joiner
051 * instance returned by the method. This makes joiners thread-safe, and safe to store as {@code
052 * static final} constants.
053 *
054 * <pre>{@code
055 * // Bad! Do not do this!
056 * Joiner joiner = Joiner.on(',');
057 * joiner.skipNulls(); // does nothing!
058 * return joiner.join("wrong", null, "wrong");
059 * }</pre>
060 *
061 * <p>See the Guava User Guide article on <a
062 * href="https://github.com/google/guava/wiki/StringsExplained#joiner">{@code Joiner}</a>.
063 *
064 * @author Kevin Bourrillion
065 * @since 2.0
066 */
067@GwtCompatible
068@ElementTypesAreNonnullByDefault
069public class Joiner {
070  /** Returns a joiner which automatically places {@code separator} between consecutive elements. */
071  public static Joiner on(String separator) {
072    return new Joiner(separator);
073  }
074
075  /** Returns a joiner which automatically places {@code separator} between consecutive elements. */
076  public static Joiner on(char separator) {
077    return new Joiner(String.valueOf(separator));
078  }
079
080  private final String separator;
081
082  private Joiner(String separator) {
083    this.separator = checkNotNull(separator);
084  }
085
086  private Joiner(Joiner prototype) {
087    this.separator = prototype.separator;
088  }
089
090  /*
091   * In this file, we use <? extends @Nullable Object> instead of <?> to work around a Kotlin bug
092   * (see b/189937072 until we file a bug against Kotlin itself). (The two should be equivalent, so
093   * we normally prefer the shorter one.)
094   */
095
096  /**
097   * Appends the string representation of each of {@code parts}, using the previously configured
098   * separator between each, to {@code appendable}.
099   */
100  @CanIgnoreReturnValue
101  public <A extends Appendable> A appendTo(A appendable, Iterable<? extends @Nullable Object> parts)
102      throws IOException {
103    return appendTo(appendable, parts.iterator());
104  }
105
106  /**
107   * Appends the string representation of each of {@code parts}, using the previously configured
108   * separator between each, to {@code appendable}.
109   *
110   * @since 11.0
111   */
112  @CanIgnoreReturnValue
113  public <A extends Appendable> A appendTo(A appendable, Iterator<? extends @Nullable Object> parts)
114      throws IOException {
115    checkNotNull(appendable);
116    if (parts.hasNext()) {
117      appendable.append(toString(parts.next()));
118      while (parts.hasNext()) {
119        appendable.append(separator);
120        appendable.append(toString(parts.next()));
121      }
122    }
123    return appendable;
124  }
125
126  /**
127   * Appends the string representation of each of {@code parts}, using the previously configured
128   * separator between each, to {@code appendable}.
129   */
130  @CanIgnoreReturnValue
131  public final <A extends Appendable> A appendTo(A appendable, @Nullable Object[] parts)
132      throws IOException {
133    @SuppressWarnings("nullness") // TODO: b/316358623 - Remove suppression after fixing checker
134    List<?> partsList = Arrays.<@Nullable Object>asList(parts);
135    return appendTo(appendable, partsList);
136  }
137
138  /** Appends to {@code appendable} the string representation of each of the remaining arguments. */
139  @CanIgnoreReturnValue
140  public final <A extends Appendable> A appendTo(
141      A appendable,
142      @CheckForNull Object first,
143      @CheckForNull Object second,
144      @Nullable Object... rest)
145      throws IOException {
146    return appendTo(appendable, iterable(first, second, rest));
147  }
148
149  /**
150   * Appends the string representation of each of {@code parts}, using the previously configured
151   * separator between each, to {@code builder}. Identical to {@link #appendTo(Appendable,
152   * Iterable)}, except that it does not throw {@link IOException}.
153   */
154  @CanIgnoreReturnValue
155  public final StringBuilder appendTo(
156      StringBuilder builder, Iterable<? extends @Nullable Object> parts) {
157    return appendTo(builder, parts.iterator());
158  }
159
160  /**
161   * Appends the string representation of each of {@code parts}, using the previously configured
162   * separator between each, to {@code builder}. Identical to {@link #appendTo(Appendable,
163   * Iterable)}, except that it does not throw {@link IOException}.
164   *
165   * @since 11.0
166   */
167  @CanIgnoreReturnValue
168  public final StringBuilder appendTo(
169      StringBuilder builder, Iterator<? extends @Nullable Object> parts) {
170    try {
171      appendTo((Appendable) builder, parts);
172    } catch (IOException impossible) {
173      throw new AssertionError(impossible);
174    }
175    return builder;
176  }
177
178  /**
179   * Appends the string representation of each of {@code parts}, using the previously configured
180   * separator between each, to {@code builder}. Identical to {@link #appendTo(Appendable,
181   * Iterable)}, except that it does not throw {@link IOException}.
182   */
183  @CanIgnoreReturnValue
184  public final StringBuilder appendTo(StringBuilder builder, @Nullable Object[] parts) {
185    @SuppressWarnings("nullness") // TODO: b/316358623 - Remove suppression after fixing checker
186    List<?> partsList = Arrays.<@Nullable Object>asList(parts);
187    return appendTo(builder, partsList);
188  }
189
190  /**
191   * Appends to {@code builder} the string representation of each of the remaining arguments.
192   * Identical to {@link #appendTo(Appendable, Object, Object, Object...)}, except that it does not
193   * throw {@link IOException}.
194   */
195  @CanIgnoreReturnValue
196  public final StringBuilder appendTo(
197      StringBuilder builder,
198      @CheckForNull Object first,
199      @CheckForNull Object second,
200      @Nullable Object... rest) {
201    return appendTo(builder, iterable(first, second, rest));
202  }
203
204  /**
205   * Returns a string containing the string representation of each of {@code parts}, using the
206   * previously configured separator between each.
207   */
208  public final String join(Iterable<? extends @Nullable Object> parts) {
209    return join(parts.iterator());
210  }
211
212  /**
213   * Returns a string containing the string representation of each of {@code parts}, using the
214   * previously configured separator between each.
215   *
216   * @since 11.0
217   */
218  public final String join(Iterator<? extends @Nullable Object> parts) {
219    return appendTo(new StringBuilder(), parts).toString();
220  }
221
222  /**
223   * Returns a string containing the string representation of each of {@code parts}, using the
224   * previously configured separator between each.
225   */
226  public final String join(@Nullable Object[] parts) {
227    @SuppressWarnings("nullness") // TODO: b/316358623 - Remove suppression after fixing checker
228    List<?> partsList = Arrays.<@Nullable Object>asList(parts);
229    return join(partsList);
230  }
231
232  /**
233   * Returns a string containing the string representation of each argument, using the previously
234   * configured separator between each.
235   */
236  public final String join(
237      @CheckForNull Object first, @CheckForNull Object second, @Nullable Object... rest) {
238    return join(iterable(first, second, rest));
239  }
240
241  /**
242   * Returns a joiner with the same behavior as this one, except automatically substituting {@code
243   * nullText} for any provided null elements.
244   */
245  public Joiner useForNull(String nullText) {
246    checkNotNull(nullText);
247    return new Joiner(this) {
248      @Override
249      CharSequence toString(@CheckForNull Object part) {
250        return (part == null) ? nullText : Joiner.this.toString(part);
251      }
252
253      @Override
254      public Joiner useForNull(String nullText) {
255        throw new UnsupportedOperationException("already specified useForNull");
256      }
257
258      @Override
259      public Joiner skipNulls() {
260        throw new UnsupportedOperationException("already specified useForNull");
261      }
262    };
263  }
264
265  /**
266   * Returns a joiner with the same behavior as this joiner, except automatically skipping over any
267   * provided null elements.
268   */
269  public Joiner skipNulls() {
270    return new Joiner(this) {
271      @Override
272      public <A extends Appendable> A appendTo(
273          A appendable, Iterator<? extends @Nullable Object> parts) throws IOException {
274        checkNotNull(appendable, "appendable");
275        checkNotNull(parts, "parts");
276        while (parts.hasNext()) {
277          Object part = parts.next();
278          if (part != null) {
279            appendable.append(Joiner.this.toString(part));
280            break;
281          }
282        }
283        while (parts.hasNext()) {
284          Object part = parts.next();
285          if (part != null) {
286            appendable.append(separator);
287            appendable.append(Joiner.this.toString(part));
288          }
289        }
290        return appendable;
291      }
292
293      @Override
294      public Joiner useForNull(String nullText) {
295        throw new UnsupportedOperationException("already specified skipNulls");
296      }
297
298      @Override
299      public MapJoiner withKeyValueSeparator(String kvs) {
300        throw new UnsupportedOperationException("can't use .skipNulls() with maps");
301      }
302    };
303  }
304
305  /**
306   * Returns a {@code MapJoiner} using the given key-value separator, and the same configuration as
307   * this {@code Joiner} otherwise.
308   *
309   * @since 20.0
310   */
311  public MapJoiner withKeyValueSeparator(char keyValueSeparator) {
312    return withKeyValueSeparator(String.valueOf(keyValueSeparator));
313  }
314
315  /**
316   * Returns a {@code MapJoiner} using the given key-value separator, and the same configuration as
317   * this {@code Joiner} otherwise.
318   */
319  public MapJoiner withKeyValueSeparator(String keyValueSeparator) {
320    return new MapJoiner(this, keyValueSeparator);
321  }
322
323  /**
324   * An object that joins map entries in the same manner as {@code Joiner} joins iterables and
325   * arrays. Like {@code Joiner}, it is thread-safe and immutable.
326   *
327   * <p>In addition to operating on {@code Map} instances, {@code MapJoiner} can operate on {@code
328   * Multimap} entries in two distinct modes:
329   *
330   * <ul>
331   *   <li>To output a separate entry for each key-value pair, pass {@code multimap.entries()} to a
332   *       {@code MapJoiner} method that accepts entries as input, and receive output of the form
333   *       {@code key1=A&key1=B&key2=C}.
334   *   <li>To output a single entry for each key, pass {@code multimap.asMap()} to a {@code
335   *       MapJoiner} method that accepts a map as input, and receive output of the form {@code
336   *       key1=[A, B]&key2=C}.
337   * </ul>
338   *
339   * @since 2.0
340   */
341  public static final class MapJoiner {
342    private final Joiner joiner;
343    private final String keyValueSeparator;
344
345    private MapJoiner(Joiner joiner, String keyValueSeparator) {
346      this.joiner = joiner; // only "this" is ever passed, so don't checkNotNull
347      this.keyValueSeparator = checkNotNull(keyValueSeparator);
348    }
349
350    /**
351     * Appends the string representation of each entry of {@code map}, using the previously
352     * configured separator and key-value separator, to {@code appendable}.
353     */
354    @CanIgnoreReturnValue
355    public <A extends Appendable> A appendTo(A appendable, Map<?, ?> map) throws IOException {
356      return appendTo(appendable, map.entrySet());
357    }
358
359    /**
360     * Appends the string representation of each entry of {@code map}, using the previously
361     * configured separator and key-value separator, to {@code builder}. Identical to {@link
362     * #appendTo(Appendable, Map)}, except that it does not throw {@link IOException}.
363     */
364    @CanIgnoreReturnValue
365    public StringBuilder appendTo(StringBuilder builder, Map<?, ?> map) {
366      return appendTo(builder, map.entrySet());
367    }
368
369    /**
370     * Appends the string representation of each entry in {@code entries}, using the previously
371     * configured separator and key-value separator, to {@code appendable}.
372     *
373     * @since 10.0
374     */
375    @CanIgnoreReturnValue
376    public <A extends Appendable> A appendTo(A appendable, Iterable<? extends Entry<?, ?>> entries)
377        throws IOException {
378      return appendTo(appendable, entries.iterator());
379    }
380
381    /**
382     * Appends the string representation of each entry in {@code entries}, using the previously
383     * configured separator and key-value separator, to {@code appendable}.
384     *
385     * @since 11.0
386     */
387    @CanIgnoreReturnValue
388    public <A extends Appendable> A appendTo(A appendable, Iterator<? extends Entry<?, ?>> parts)
389        throws IOException {
390      checkNotNull(appendable);
391      if (parts.hasNext()) {
392        Entry<?, ?> entry = parts.next();
393        appendable.append(joiner.toString(entry.getKey()));
394        appendable.append(keyValueSeparator);
395        appendable.append(joiner.toString(entry.getValue()));
396        while (parts.hasNext()) {
397          appendable.append(joiner.separator);
398          Entry<?, ?> e = parts.next();
399          appendable.append(joiner.toString(e.getKey()));
400          appendable.append(keyValueSeparator);
401          appendable.append(joiner.toString(e.getValue()));
402        }
403      }
404      return appendable;
405    }
406
407    /**
408     * Appends the string representation of each entry in {@code entries}, using the previously
409     * configured separator and key-value separator, to {@code builder}. Identical to {@link
410     * #appendTo(Appendable, Iterable)}, except that it does not throw {@link IOException}.
411     *
412     * @since 10.0
413     */
414    @CanIgnoreReturnValue
415    public StringBuilder appendTo(StringBuilder builder, Iterable<? extends Entry<?, ?>> entries) {
416      return appendTo(builder, entries.iterator());
417    }
418
419    /**
420     * Appends the string representation of each entry in {@code entries}, using the previously
421     * configured separator and key-value separator, to {@code builder}. Identical to {@link
422     * #appendTo(Appendable, Iterable)}, except that it does not throw {@link IOException}.
423     *
424     * @since 11.0
425     */
426    @CanIgnoreReturnValue
427    public StringBuilder appendTo(StringBuilder builder, Iterator<? extends Entry<?, ?>> entries) {
428      try {
429        appendTo((Appendable) builder, entries);
430      } catch (IOException impossible) {
431        throw new AssertionError(impossible);
432      }
433      return builder;
434    }
435
436    /**
437     * Returns a string containing the string representation of each entry of {@code map}, using the
438     * previously configured separator and key-value separator.
439     */
440    public String join(Map<?, ?> map) {
441      return join(map.entrySet());
442    }
443
444    /**
445     * Returns a string containing the string representation of each entry in {@code entries}, using
446     * the previously configured separator and key-value separator.
447     *
448     * @since 10.0
449     */
450    public String join(Iterable<? extends Entry<?, ?>> entries) {
451      return join(entries.iterator());
452    }
453
454    /**
455     * Returns a string containing the string representation of each entry in {@code entries}, using
456     * the previously configured separator and key-value separator.
457     *
458     * @since 11.0
459     */
460    public String join(Iterator<? extends Entry<?, ?>> entries) {
461      return appendTo(new StringBuilder(), entries).toString();
462    }
463
464    /**
465     * Returns a map joiner with the same behavior as this one, except automatically substituting
466     * {@code nullText} for any provided null keys or values.
467     */
468    public MapJoiner useForNull(String nullText) {
469      return new MapJoiner(joiner.useForNull(nullText), keyValueSeparator);
470    }
471  }
472
473  CharSequence toString(@CheckForNull Object part) {
474    /*
475     * requireNonNull is not safe: Joiner.on(...).join(somethingThatContainsNull) will indeed throw.
476     * However, Joiner.on(...).useForNull(...).join(somethingThatContainsNull) *is* safe -- because
477     * it returns a subclass of Joiner that overrides this method to tolerate null inputs.
478     *
479     * Unfortunately, we don't distinguish between these two cases in our public API: Joiner.on(...)
480     * and Joiner.on(...).useForNull(...) both declare the same return type: plain Joiner. To ensure
481     * that users *can* pass null arguments to Joiner, we annotate it as if it always tolerates null
482     * inputs, rather than as if it never tolerates them.
483     *
484     * We rely on checkers to implement special cases to catch dangerous calls to join(), etc. based
485     * on what they know about the particular Joiner instances the calls are performed on.
486     *
487     * (In addition to useForNull, we also offer skipNulls. It, too, tolerates null inputs, but its
488     * tolerance is implemented differently: Its implementation avoids calling this toString(Object)
489     * method in the first place.)
490     */
491    requireNonNull(part);
492    return (part instanceof CharSequence) ? (CharSequence) part : part.toString();
493  }
494
495  private static Iterable<@Nullable Object> iterable(
496      @CheckForNull Object first, @CheckForNull Object second, @Nullable Object[] rest) {
497    checkNotNull(rest);
498    return new AbstractList<@Nullable Object>() {
499      @Override
500      public int size() {
501        return rest.length + 2;
502      }
503
504      @Override
505      @CheckForNull
506      public Object get(int index) {
507        switch (index) {
508          case 0:
509            return first;
510          case 1:
511            return second;
512          default:
513            return rest[index - 2];
514        }
515      }
516    };
517  }
518}