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.Beta; 021import com.google.common.annotations.GwtCompatible; 022import com.google.errorprone.annotations.CanIgnoreReturnValue; 023import java.io.IOException; 024import java.util.AbstractList; 025import java.util.Arrays; 026import java.util.Iterator; 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 return appendTo(appendable, Arrays.asList(parts)); 134 } 135 136 /** Appends to {@code appendable} the string representation of each of the remaining arguments. */ 137 @CanIgnoreReturnValue 138 public final <A extends Appendable> A appendTo( 139 A appendable, 140 @CheckForNull Object first, 141 @CheckForNull Object second, 142 @Nullable Object... rest) 143 throws IOException { 144 return appendTo(appendable, iterable(first, second, rest)); 145 } 146 147 /** 148 * Appends the string representation of each of {@code parts}, using the previously configured 149 * separator between each, to {@code builder}. Identical to {@link #appendTo(Appendable, 150 * Iterable)}, except that it does not throw {@link IOException}. 151 */ 152 @CanIgnoreReturnValue 153 public final StringBuilder appendTo( 154 StringBuilder builder, Iterable<? extends @Nullable Object> parts) { 155 return appendTo(builder, parts.iterator()); 156 } 157 158 /** 159 * Appends the string representation of each of {@code parts}, using the previously configured 160 * separator between each, to {@code builder}. Identical to {@link #appendTo(Appendable, 161 * Iterable)}, except that it does not throw {@link IOException}. 162 * 163 * @since 11.0 164 */ 165 @CanIgnoreReturnValue 166 public final StringBuilder appendTo( 167 StringBuilder builder, Iterator<? extends @Nullable Object> parts) { 168 try { 169 appendTo((Appendable) builder, parts); 170 } catch (IOException impossible) { 171 throw new AssertionError(impossible); 172 } 173 return builder; 174 } 175 176 /** 177 * Appends the string representation of each of {@code parts}, using the previously configured 178 * separator between each, to {@code builder}. Identical to {@link #appendTo(Appendable, 179 * Iterable)}, except that it does not throw {@link IOException}. 180 */ 181 @CanIgnoreReturnValue 182 public final StringBuilder appendTo(StringBuilder builder, @Nullable Object[] parts) { 183 return appendTo(builder, Arrays.asList(parts)); 184 } 185 186 /** 187 * Appends to {@code builder} the string representation of each of the remaining arguments. 188 * Identical to {@link #appendTo(Appendable, Object, Object, Object...)}, except that it does not 189 * throw {@link IOException}. 190 */ 191 @CanIgnoreReturnValue 192 public final StringBuilder appendTo( 193 StringBuilder builder, 194 @CheckForNull Object first, 195 @CheckForNull Object second, 196 @Nullable Object... rest) { 197 return appendTo(builder, iterable(first, second, rest)); 198 } 199 200 /** 201 * Returns a string containing the string representation of each of {@code parts}, using the 202 * previously configured separator between each. 203 */ 204 public final String join(Iterable<? extends @Nullable Object> parts) { 205 return join(parts.iterator()); 206 } 207 208 /** 209 * Returns a string containing the string representation of each of {@code parts}, using the 210 * previously configured separator between each. 211 * 212 * @since 11.0 213 */ 214 public final String join(Iterator<? extends @Nullable Object> parts) { 215 return appendTo(new StringBuilder(), parts).toString(); 216 } 217 218 /** 219 * Returns a string containing the string representation of each of {@code parts}, using the 220 * previously configured separator between each. 221 */ 222 public final String join(@Nullable Object[] parts) { 223 return join(Arrays.asList(parts)); 224 } 225 226 /** 227 * Returns a string containing the string representation of each argument, using the previously 228 * configured separator between each. 229 */ 230 public final String join( 231 @CheckForNull Object first, @CheckForNull Object second, @Nullable Object... rest) { 232 return join(iterable(first, second, rest)); 233 } 234 235 /** 236 * Returns a joiner with the same behavior as this one, except automatically substituting {@code 237 * nullText} for any provided null elements. 238 */ 239 public Joiner useForNull(final String nullText) { 240 checkNotNull(nullText); 241 return new Joiner(this) { 242 @Override 243 CharSequence toString(@CheckForNull Object part) { 244 return (part == null) ? nullText : Joiner.this.toString(part); 245 } 246 247 @Override 248 public Joiner useForNull(String nullText) { 249 throw new UnsupportedOperationException("already specified useForNull"); 250 } 251 252 @Override 253 public Joiner skipNulls() { 254 throw new UnsupportedOperationException("already specified useForNull"); 255 } 256 }; 257 } 258 259 /** 260 * Returns a joiner with the same behavior as this joiner, except automatically skipping over any 261 * provided null elements. 262 */ 263 public Joiner skipNulls() { 264 return new Joiner(this) { 265 @Override 266 public <A extends Appendable> A appendTo( 267 A appendable, Iterator<? extends @Nullable Object> parts) throws IOException { 268 checkNotNull(appendable, "appendable"); 269 checkNotNull(parts, "parts"); 270 while (parts.hasNext()) { 271 Object part = parts.next(); 272 if (part != null) { 273 appendable.append(Joiner.this.toString(part)); 274 break; 275 } 276 } 277 while (parts.hasNext()) { 278 Object part = parts.next(); 279 if (part != null) { 280 appendable.append(separator); 281 appendable.append(Joiner.this.toString(part)); 282 } 283 } 284 return appendable; 285 } 286 287 @Override 288 public Joiner useForNull(String nullText) { 289 throw new UnsupportedOperationException("already specified skipNulls"); 290 } 291 292 @Override 293 public MapJoiner withKeyValueSeparator(String kvs) { 294 throw new UnsupportedOperationException("can't use .skipNulls() with maps"); 295 } 296 }; 297 } 298 299 /** 300 * Returns a {@code MapJoiner} using the given key-value separator, and the same configuration as 301 * this {@code Joiner} otherwise. 302 * 303 * @since 20.0 304 */ 305 public MapJoiner withKeyValueSeparator(char keyValueSeparator) { 306 return withKeyValueSeparator(String.valueOf(keyValueSeparator)); 307 } 308 309 /** 310 * Returns a {@code MapJoiner} using the given key-value separator, and the same configuration as 311 * this {@code Joiner} otherwise. 312 */ 313 public MapJoiner withKeyValueSeparator(String keyValueSeparator) { 314 return new MapJoiner(this, keyValueSeparator); 315 } 316 317 /** 318 * An object that joins map entries in the same manner as {@code Joiner} joins iterables and 319 * arrays. Like {@code Joiner}, it is thread-safe and immutable. 320 * 321 * <p>In addition to operating on {@code Map} instances, {@code MapJoiner} can operate on {@code 322 * Multimap} entries in two distinct modes: 323 * 324 * <ul> 325 * <li>To output a separate entry for each key-value pair, pass {@code multimap.entries()} to a 326 * {@code MapJoiner} method that accepts entries as input, and receive output of the form 327 * {@code key1=A&key1=B&key2=C}. 328 * <li>To output a single entry for each key, pass {@code multimap.asMap()} to a {@code 329 * MapJoiner} method that accepts a map as input, and receive output of the form {@code 330 * key1=[A, B]&key2=C}. 331 * </ul> 332 * 333 * @since 2.0 334 */ 335 public static final class MapJoiner { 336 private final Joiner joiner; 337 private final String keyValueSeparator; 338 339 private MapJoiner(Joiner joiner, String keyValueSeparator) { 340 this.joiner = joiner; // only "this" is ever passed, so don't checkNotNull 341 this.keyValueSeparator = checkNotNull(keyValueSeparator); 342 } 343 344 /** 345 * Appends the string representation of each entry of {@code map}, using the previously 346 * configured separator and key-value separator, to {@code appendable}. 347 */ 348 @CanIgnoreReturnValue 349 public <A extends Appendable> A appendTo(A appendable, Map<?, ?> map) throws IOException { 350 return appendTo(appendable, map.entrySet()); 351 } 352 353 /** 354 * Appends the string representation of each entry of {@code map}, using the previously 355 * configured separator and key-value separator, to {@code builder}. Identical to {@link 356 * #appendTo(Appendable, Map)}, except that it does not throw {@link IOException}. 357 */ 358 @CanIgnoreReturnValue 359 public StringBuilder appendTo(StringBuilder builder, Map<?, ?> map) { 360 return appendTo(builder, map.entrySet()); 361 } 362 363 /** 364 * Appends the string representation of each entry in {@code entries}, using the previously 365 * configured separator and key-value separator, to {@code appendable}. 366 * 367 * @since 10.0 368 */ 369 @Beta 370 @CanIgnoreReturnValue 371 public <A extends Appendable> A appendTo(A appendable, Iterable<? extends Entry<?, ?>> entries) 372 throws IOException { 373 return appendTo(appendable, entries.iterator()); 374 } 375 376 /** 377 * Appends the string representation of each entry in {@code entries}, using the previously 378 * configured separator and key-value separator, to {@code appendable}. 379 * 380 * @since 11.0 381 */ 382 @Beta 383 @CanIgnoreReturnValue 384 public <A extends Appendable> A appendTo(A appendable, Iterator<? extends Entry<?, ?>> parts) 385 throws IOException { 386 checkNotNull(appendable); 387 if (parts.hasNext()) { 388 Entry<?, ?> entry = parts.next(); 389 appendable.append(joiner.toString(entry.getKey())); 390 appendable.append(keyValueSeparator); 391 appendable.append(joiner.toString(entry.getValue())); 392 while (parts.hasNext()) { 393 appendable.append(joiner.separator); 394 Entry<?, ?> e = parts.next(); 395 appendable.append(joiner.toString(e.getKey())); 396 appendable.append(keyValueSeparator); 397 appendable.append(joiner.toString(e.getValue())); 398 } 399 } 400 return appendable; 401 } 402 403 /** 404 * Appends the string representation of each entry in {@code entries}, using the previously 405 * configured separator and key-value separator, to {@code builder}. Identical to {@link 406 * #appendTo(Appendable, Iterable)}, except that it does not throw {@link IOException}. 407 * 408 * @since 10.0 409 */ 410 @Beta 411 @CanIgnoreReturnValue 412 public StringBuilder appendTo(StringBuilder builder, Iterable<? extends Entry<?, ?>> entries) { 413 return appendTo(builder, entries.iterator()); 414 } 415 416 /** 417 * Appends the string representation of each entry in {@code entries}, using the previously 418 * configured separator and key-value separator, to {@code builder}. Identical to {@link 419 * #appendTo(Appendable, Iterable)}, except that it does not throw {@link IOException}. 420 * 421 * @since 11.0 422 */ 423 @Beta 424 @CanIgnoreReturnValue 425 public StringBuilder appendTo(StringBuilder builder, Iterator<? extends Entry<?, ?>> entries) { 426 try { 427 appendTo((Appendable) builder, entries); 428 } catch (IOException impossible) { 429 throw new AssertionError(impossible); 430 } 431 return builder; 432 } 433 434 /** 435 * Returns a string containing the string representation of each entry of {@code map}, using the 436 * previously configured separator and key-value separator. 437 */ 438 public String join(Map<?, ?> map) { 439 return join(map.entrySet()); 440 } 441 442 /** 443 * Returns a string containing the string representation of each entry in {@code entries}, using 444 * the previously configured separator and key-value separator. 445 * 446 * @since 10.0 447 */ 448 @Beta 449 public String join(Iterable<? extends Entry<?, ?>> entries) { 450 return join(entries.iterator()); 451 } 452 453 /** 454 * Returns a string containing the string representation of each entry in {@code entries}, using 455 * the previously configured separator and key-value separator. 456 * 457 * @since 11.0 458 */ 459 @Beta 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 final Object first, 497 @CheckForNull final Object second, 498 final @Nullable Object[] rest) { 499 checkNotNull(rest); 500 return new AbstractList<@Nullable Object>() { 501 @Override 502 public int size() { 503 return rest.length + 2; 504 } 505 506 @Override 507 @CheckForNull 508 public Object get(int index) { 509 switch (index) { 510 case 0: 511 return first; 512 case 1: 513 return second; 514 default: 515 return rest[index - 2]; 516 } 517 } 518 }; 519 } 520}