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}