001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect; 018 019import static com.google.common.base.Preconditions.checkElementIndex; 020import static com.google.common.base.Preconditions.checkNotNull; 021import static com.google.common.base.Preconditions.checkPositionIndexes; 022import static com.google.common.collect.ObjectArrays.checkElementsNotNull; 023import static com.google.common.collect.RegularImmutableList.EMPTY; 024 025import com.google.common.annotations.Beta; 026import com.google.common.annotations.GwtCompatible; 027import com.google.errorprone.annotations.CanIgnoreReturnValue; 028import java.io.InvalidObjectException; 029import java.io.ObjectInputStream; 030import java.io.Serializable; 031import java.util.Arrays; 032import java.util.Collection; 033import java.util.Collections; 034import java.util.Comparator; 035import java.util.Iterator; 036import java.util.List; 037import java.util.RandomAccess; 038import java.util.Spliterator; 039import java.util.function.Consumer; 040import java.util.function.UnaryOperator; 041import java.util.stream.Collector; 042import javax.annotation.Nullable; 043 044/** 045 * A {@link List} whose contents will never change, with many other important properties detailed at 046 * {@link ImmutableCollection}. 047 * 048 * <p>See the Guava User Guide article on <a href= 049 * "https://github.com/google/guava/wiki/ImmutableCollectionsExplained"> 050 * immutable collections</a>. 051 * 052 * @see ImmutableMap 053 * @see ImmutableSet 054 * @author Kevin Bourrillion 055 * @since 2.0 056 */ 057@GwtCompatible(serializable = true, emulated = true) 058@SuppressWarnings("serial") // we're overriding default serialization 059public abstract class ImmutableList<E> extends ImmutableCollection<E> 060 implements List<E>, RandomAccess { 061 062 /** 063 * Returns a {@code Collector} that accumulates the input elements into a new 064 * {@code ImmutableList}, in encounter order. 065 * 066 * @since 21.0 067 */ 068 @Beta 069 public static <E> Collector<E, ?, ImmutableList<E>> toImmutableList() { 070 return CollectCollectors.toImmutableList(); 071 } 072 073 /** 074 * Returns the empty immutable list. This list behaves and performs comparably 075 * to {@link Collections#emptyList}, and is preferable mainly for consistency 076 * and maintainability of your code. 077 */ 078 // Casting to any type is safe because the list will never hold any elements. 079 @SuppressWarnings("unchecked") 080 public static <E> ImmutableList<E> of() { 081 return (ImmutableList<E>) EMPTY; 082 } 083 084 /** 085 * Returns an immutable list containing a single element. This list behaves 086 * and performs comparably to {@link Collections#singleton}, but will not 087 * accept a null element. It is preferable mainly for consistency and 088 * maintainability of your code. 089 * 090 * @throws NullPointerException if {@code element} is null 091 */ 092 public static <E> ImmutableList<E> of(E element) { 093 return construct(element); 094 } 095 096 /** 097 * Returns an immutable list containing the given elements, in order. 098 * 099 * @throws NullPointerException if any element is null 100 */ 101 public static <E> ImmutableList<E> of(E e1, E e2) { 102 return construct(e1, e2); 103 } 104 105 /** 106 * Returns an immutable list containing the given elements, in order. 107 * 108 * @throws NullPointerException if any element is null 109 */ 110 public static <E> ImmutableList<E> of(E e1, E e2, E e3) { 111 return construct(e1, e2, e3); 112 } 113 114 /** 115 * Returns an immutable list containing the given elements, in order. 116 * 117 * @throws NullPointerException if any element is null 118 */ 119 public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4) { 120 return construct(e1, e2, e3, e4); 121 } 122 123 /** 124 * Returns an immutable list containing the given elements, in order. 125 * 126 * @throws NullPointerException if any element is null 127 */ 128 public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5) { 129 return construct(e1, e2, e3, e4, e5); 130 } 131 132 /** 133 * Returns an immutable list containing the given elements, in order. 134 * 135 * @throws NullPointerException if any element is null 136 */ 137 public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6) { 138 return construct(e1, e2, e3, e4, e5, e6); 139 } 140 141 /** 142 * Returns an immutable list containing the given elements, in order. 143 * 144 * @throws NullPointerException if any element is null 145 */ 146 public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) { 147 return construct(e1, e2, e3, e4, e5, e6, e7); 148 } 149 150 /** 151 * Returns an immutable list containing the given elements, in order. 152 * 153 * @throws NullPointerException if any element is null 154 */ 155 public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) { 156 return construct(e1, e2, e3, e4, e5, e6, e7, e8); 157 } 158 159 /** 160 * Returns an immutable list containing the given elements, in order. 161 * 162 * @throws NullPointerException if any element is null 163 */ 164 public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) { 165 return construct(e1, e2, e3, e4, e5, e6, e7, e8, e9); 166 } 167 168 /** 169 * Returns an immutable list containing the given elements, in order. 170 * 171 * @throws NullPointerException if any element is null 172 */ 173 public static <E> ImmutableList<E> of( 174 E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) { 175 return construct(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10); 176 } 177 178 /** 179 * Returns an immutable list containing the given elements, in order. 180 * 181 * @throws NullPointerException if any element is null 182 */ 183 public static <E> ImmutableList<E> of( 184 E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E e11) { 185 return construct(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10, e11); 186 } 187 188 // These go up to eleven. After that, you just get the varargs form, and 189 // whatever warnings might come along with it. :( 190 191 /** 192 * Returns an immutable list containing the given elements, in order. 193 * 194 * @throws NullPointerException if any element is null 195 * @since 3.0 (source-compatible since 2.0) 196 */ 197 @SafeVarargs // For Eclipse. For internal javac we have disabled this pointless type of warning. 198 public static <E> ImmutableList<E> of( 199 E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E e11, E e12, E... others) { 200 Object[] array = new Object[12 + others.length]; 201 array[0] = e1; 202 array[1] = e2; 203 array[2] = e3; 204 array[3] = e4; 205 array[4] = e5; 206 array[5] = e6; 207 array[6] = e7; 208 array[7] = e8; 209 array[8] = e9; 210 array[9] = e10; 211 array[10] = e11; 212 array[11] = e12; 213 System.arraycopy(others, 0, array, 12, others.length); 214 return construct(array); 215 } 216 217 /** 218 * Returns an immutable list containing the given elements, in order. If 219 * {@code elements} is a {@link Collection}, this method behaves exactly as 220 * {@link #copyOf(Collection)}; otherwise, it behaves exactly as {@code 221 * copyOf(elements.iterator()}. 222 * 223 * @throws NullPointerException if any of {@code elements} is null 224 */ 225 public static <E> ImmutableList<E> copyOf(Iterable<? extends E> elements) { 226 checkNotNull(elements); // TODO(kevinb): is this here only for GWT? 227 return (elements instanceof Collection) 228 ? copyOf((Collection<? extends E>) elements) 229 : copyOf(elements.iterator()); 230 } 231 232 /** 233 * Returns an immutable list containing the given elements, in order. 234 * 235 * <p>Despite the method name, this method attempts to avoid actually copying 236 * the data when it is safe to do so. The exact circumstances under which a 237 * copy will or will not be performed are undocumented and subject to change. 238 * 239 * <p>Note that if {@code list} is a {@code List<String>}, then {@code 240 * ImmutableList.copyOf(list)} returns an {@code ImmutableList<String>} 241 * containing each of the strings in {@code list}, while 242 * ImmutableList.of(list)} returns an {@code ImmutableList<List<String>>} 243 * containing one element (the given list itself). 244 * 245 * <p>This method is safe to use even when {@code elements} is a synchronized 246 * or concurrent collection that is currently being modified by another 247 * thread. 248 * 249 * @throws NullPointerException if any of {@code elements} is null 250 */ 251 public static <E> ImmutableList<E> copyOf(Collection<? extends E> elements) { 252 if (elements instanceof ImmutableCollection) { 253 @SuppressWarnings("unchecked") // all supported methods are covariant 254 ImmutableList<E> list = ((ImmutableCollection<E>) elements).asList(); 255 return list.isPartialView() ? ImmutableList.<E>asImmutableList(list.toArray()) : list; 256 } 257 return construct(elements.toArray()); 258 } 259 260 /** 261 * Returns an immutable list containing the given elements, in order. 262 * 263 * @throws NullPointerException if any of {@code elements} is null 264 */ 265 public static <E> ImmutableList<E> copyOf(Iterator<? extends E> elements) { 266 // We special-case for 0 or 1 elements, but going further is madness. 267 if (!elements.hasNext()) { 268 return of(); 269 } 270 E first = elements.next(); 271 if (!elements.hasNext()) { 272 return of(first); 273 } else { 274 return new ImmutableList.Builder<E>().add(first).addAll(elements).build(); 275 } 276 } 277 278 /** 279 * Returns an immutable list containing the given elements, in order. 280 * 281 * @throws NullPointerException if any of {@code elements} is null 282 * @since 3.0 283 */ 284 public static <E> ImmutableList<E> copyOf(E[] elements) { 285 return (elements.length == 0) 286 ? ImmutableList.<E>of() 287 : construct(elements.clone()); 288 } 289 290 /** 291 * Returns an immutable list containing the given elements, sorted according to their natural 292 * order. The sorting algorithm used is stable, so elements that compare as equal will stay in the 293 * order in which they appear in the input. 294 * 295 * <p>If your data has no duplicates, or you wish to deduplicate elements, use {@code 296 * ImmutableSortedSet.copyOf(elements)}; if you want a {@code List} you can use its {@code 297 * asList()} view. 298 * 299 * <p><b>Java 8 users:</b> If you want to convert a {@link java.util.stream.Stream} to a sorted 300 * {@code ImmutableList}, use {@code stream.sorted().collect(toImmutableList())}. 301 * 302 * @throws NullPointerException if any element in the input is null 303 * @since 21.0 304 */ 305 public static <E extends Comparable<? super E>> ImmutableList<E> sortedCopyOf( 306 Iterable<? extends E> elements) { 307 Comparable<?>[] array = Iterables.toArray(elements, new Comparable<?>[0]); 308 checkElementsNotNull((Object[]) array); 309 Arrays.sort(array); 310 return asImmutableList(array); 311 } 312 313 /** 314 * Returns an immutable list containing the given elements, in sorted order relative to the 315 * specified comparator. The sorting algorithm used is stable, so elements that compare as equal 316 * will stay in the order in which they appear in the input. 317 * 318 * <p>If your data has no duplicates, or you wish to deduplicate elements, use {@code 319 * ImmutableSortedSet.copyOf(comparator, elements)}; if you want a {@code List} you can use its 320 * {@code asList()} view. 321 * 322 * <p><b>Java 8 users:</b> If you want to convert a {@link java.util.stream.Stream} to a sorted 323 * {@code ImmutableList}, use {@code stream.sorted(comparator).collect(toImmutableList())}. 324 * 325 * @throws NullPointerException if any element in the input is null 326 * @since 21.0 327 */ 328 public static <E> ImmutableList<E> sortedCopyOf( 329 Comparator<? super E> comparator, Iterable<? extends E> elements) { 330 checkNotNull(comparator); 331 @SuppressWarnings("unchecked") // all supported methods are covariant 332 E[] array = (E[]) Iterables.toArray(elements); 333 checkElementsNotNull(array); 334 Arrays.sort(array, comparator); 335 return asImmutableList(array); 336 } 337 338 /** 339 * Views the array as an immutable list. Checks for nulls; does not copy. 340 */ 341 private static <E> ImmutableList<E> construct(Object... elements) { 342 return asImmutableList(checkElementsNotNull(elements)); 343 } 344 345 /** 346 * Views the array as an immutable list. Does not check for nulls; does not copy. 347 * 348 * <p>The array must be internally created. 349 */ 350 static <E> ImmutableList<E> asImmutableList(Object[] elements) { 351 return asImmutableList(elements, elements.length); 352 } 353 354 /** 355 * Views the array as an immutable list. Copies if the specified range does not cover the complete 356 * array. Does not check for nulls. 357 */ 358 static <E> ImmutableList<E> asImmutableList(Object[] elements, int length) { 359 if (length == 0) { 360 return of(); 361 } 362 if (length < elements.length) { 363 elements = Arrays.copyOf(elements, length); 364 } 365 return new RegularImmutableList<E>(elements); 366 } 367 368 ImmutableList() {} 369 370 // This declaration is needed to make List.iterator() and 371 // ImmutableCollection.iterator() consistent. 372 @Override 373 public UnmodifiableIterator<E> iterator() { 374 return listIterator(); 375 } 376 377 @Override 378 public UnmodifiableListIterator<E> listIterator() { 379 return listIterator(0); 380 } 381 382 @Override 383 public UnmodifiableListIterator<E> listIterator(int index) { 384 return new AbstractIndexedListIterator<E>(size(), index) { 385 @Override 386 protected E get(int index) { 387 return ImmutableList.this.get(index); 388 } 389 }; 390 } 391 392 @Override 393 public void forEach(Consumer<? super E> consumer) { 394 checkNotNull(consumer); 395 int n = size(); 396 for (int i = 0; i < n; i++) { 397 consumer.accept(get(i)); 398 } 399 } 400 401 @Override 402 public int indexOf(@Nullable Object object) { 403 return (object == null) ? -1 : Lists.indexOfImpl(this, object); 404 } 405 406 @Override 407 public int lastIndexOf(@Nullable Object object) { 408 return (object == null) ? -1 : Lists.lastIndexOfImpl(this, object); 409 } 410 411 @Override 412 public boolean contains(@Nullable Object object) { 413 return indexOf(object) >= 0; 414 } 415 416 // constrain the return type to ImmutableList<E> 417 418 /** 419 * Returns an immutable list of the elements between the specified {@code 420 * fromIndex}, inclusive, and {@code toIndex}, exclusive. (If {@code 421 * fromIndex} and {@code toIndex} are equal, the empty immutable list is 422 * returned.) 423 */ 424 @Override 425 public ImmutableList<E> subList(int fromIndex, int toIndex) { 426 checkPositionIndexes(fromIndex, toIndex, size()); 427 int length = toIndex - fromIndex; 428 if (length == size()) { 429 return this; 430 } else if (length == 0) { 431 return of(); 432 } else { 433 return subListUnchecked(fromIndex, toIndex); 434 } 435 } 436 437 /** 438 * Called by the default implementation of {@link #subList} when {@code 439 * toIndex - fromIndex > 1}, after index validation has already been 440 * performed. 441 */ 442 ImmutableList<E> subListUnchecked(int fromIndex, int toIndex) { 443 return new SubList(fromIndex, toIndex - fromIndex); 444 } 445 446 class SubList extends ImmutableList<E> { 447 final transient int offset; 448 final transient int length; 449 450 SubList(int offset, int length) { 451 this.offset = offset; 452 this.length = length; 453 } 454 455 @Override 456 public int size() { 457 return length; 458 } 459 460 @Override 461 public E get(int index) { 462 checkElementIndex(index, length); 463 return ImmutableList.this.get(index + offset); 464 } 465 466 @Override 467 public ImmutableList<E> subList(int fromIndex, int toIndex) { 468 checkPositionIndexes(fromIndex, toIndex, length); 469 return ImmutableList.this.subList(fromIndex + offset, toIndex + offset); 470 } 471 472 @Override 473 boolean isPartialView() { 474 return true; 475 } 476 } 477 478 /** 479 * Guaranteed to throw an exception and leave the list unmodified. 480 * 481 * @throws UnsupportedOperationException always 482 * @deprecated Unsupported operation. 483 */ 484 @CanIgnoreReturnValue 485 @Deprecated 486 @Override 487 public final boolean addAll(int index, Collection<? extends E> newElements) { 488 throw new UnsupportedOperationException(); 489 } 490 491 /** 492 * Guaranteed to throw an exception and leave the list unmodified. 493 * 494 * @throws UnsupportedOperationException always 495 * @deprecated Unsupported operation. 496 */ 497 @CanIgnoreReturnValue 498 @Deprecated 499 @Override 500 public final E set(int index, E element) { 501 throw new UnsupportedOperationException(); 502 } 503 504 /** 505 * Guaranteed to throw an exception and leave the list unmodified. 506 * 507 * @throws UnsupportedOperationException always 508 * @deprecated Unsupported operation. 509 */ 510 @Deprecated 511 @Override 512 public final void add(int index, E element) { 513 throw new UnsupportedOperationException(); 514 } 515 516 /** 517 * Guaranteed to throw an exception and leave the list unmodified. 518 * 519 * @throws UnsupportedOperationException always 520 * @deprecated Unsupported operation. 521 */ 522 @CanIgnoreReturnValue 523 @Deprecated 524 @Override 525 public final E remove(int index) { 526 throw new UnsupportedOperationException(); 527 } 528 529 /** 530 * Guaranteed to throw an exception and leave the list unmodified. 531 * 532 * @throws UnsupportedOperationException always 533 * @deprecated Unsupported operation. 534 */ 535 @Deprecated 536 @Override 537 public final void replaceAll(UnaryOperator<E> operator) { 538 throw new UnsupportedOperationException(); 539 } 540 541 /** 542 * Guaranteed to throw an exception and leave the list unmodified. 543 * 544 * @throws UnsupportedOperationException always 545 * @deprecated Unsupported operation. 546 */ 547 @Deprecated 548 @Override 549 public final void sort(Comparator<? super E> c) { 550 throw new UnsupportedOperationException(); 551 } 552 553 /** 554 * Returns this list instance. 555 * 556 * @since 2.0 557 */ 558 @Override 559 public final ImmutableList<E> asList() { 560 return this; 561 } 562 563 @Override 564 public Spliterator<E> spliterator() { 565 return CollectSpliterators.indexed(size(), SPLITERATOR_CHARACTERISTICS, this::get); 566 } 567 568 @Override 569 int copyIntoArray(Object[] dst, int offset) { 570 // this loop is faster for RandomAccess instances, which ImmutableLists are 571 int size = size(); 572 for (int i = 0; i < size; i++) { 573 dst[offset + i] = get(i); 574 } 575 return offset + size; 576 } 577 578 /** 579 * Returns a view of this immutable list in reverse order. For example, {@code 580 * ImmutableList.of(1, 2, 3).reverse()} is equivalent to {@code 581 * ImmutableList.of(3, 2, 1)}. 582 * 583 * @return a view of this immutable list in reverse order 584 * @since 7.0 585 */ 586 public ImmutableList<E> reverse() { 587 return (size() <= 1) ? this : new ReverseImmutableList<E>(this); 588 } 589 590 private static class ReverseImmutableList<E> extends ImmutableList<E> { 591 private final transient ImmutableList<E> forwardList; 592 593 ReverseImmutableList(ImmutableList<E> backingList) { 594 this.forwardList = backingList; 595 } 596 597 private int reverseIndex(int index) { 598 return (size() - 1) - index; 599 } 600 601 private int reversePosition(int index) { 602 return size() - index; 603 } 604 605 @Override 606 public ImmutableList<E> reverse() { 607 return forwardList; 608 } 609 610 @Override 611 public boolean contains(@Nullable Object object) { 612 return forwardList.contains(object); 613 } 614 615 @Override 616 public int indexOf(@Nullable Object object) { 617 int index = forwardList.lastIndexOf(object); 618 return (index >= 0) ? reverseIndex(index) : -1; 619 } 620 621 @Override 622 public int lastIndexOf(@Nullable Object object) { 623 int index = forwardList.indexOf(object); 624 return (index >= 0) ? reverseIndex(index) : -1; 625 } 626 627 @Override 628 public ImmutableList<E> subList(int fromIndex, int toIndex) { 629 checkPositionIndexes(fromIndex, toIndex, size()); 630 return forwardList.subList(reversePosition(toIndex), reversePosition(fromIndex)).reverse(); 631 } 632 633 @Override 634 public E get(int index) { 635 checkElementIndex(index, size()); 636 return forwardList.get(reverseIndex(index)); 637 } 638 639 @Override 640 public int size() { 641 return forwardList.size(); 642 } 643 644 @Override 645 boolean isPartialView() { 646 return forwardList.isPartialView(); 647 } 648 } 649 650 @Override 651 public boolean equals(@Nullable Object obj) { 652 return Lists.equalsImpl(this, obj); 653 } 654 655 @Override 656 public int hashCode() { 657 int hashCode = 1; 658 int n = size(); 659 for (int i = 0; i < n; i++) { 660 hashCode = 31 * hashCode + get(i).hashCode(); 661 662 hashCode = ~~hashCode; 663 // needed to deal with GWT integer overflow 664 } 665 return hashCode; 666 } 667 668 /* 669 * Serializes ImmutableLists as their logical contents. This ensures that 670 * implementation types do not leak into the serialized representation. 671 */ 672 static class SerializedForm implements Serializable { 673 final Object[] elements; 674 675 SerializedForm(Object[] elements) { 676 this.elements = elements; 677 } 678 679 Object readResolve() { 680 return copyOf(elements); 681 } 682 683 private static final long serialVersionUID = 0; 684 } 685 686 private void readObject(ObjectInputStream stream) throws InvalidObjectException { 687 throw new InvalidObjectException("Use SerializedForm"); 688 } 689 690 @Override 691 Object writeReplace() { 692 return new SerializedForm(toArray()); 693 } 694 695 /** 696 * Returns a new builder. The generated builder is equivalent to the builder 697 * created by the {@link Builder} constructor. 698 */ 699 public static <E> Builder<E> builder() { 700 return new Builder<E>(); 701 } 702 703 /** 704 * A builder for creating immutable list instances, especially {@code public 705 * static final} lists ("constant lists"). Example: <pre> {@code 706 * 707 * public static final ImmutableList<Color> GOOGLE_COLORS 708 * = new ImmutableList.Builder<Color>() 709 * .addAll(WEBSAFE_COLORS) 710 * .add(new Color(0, 191, 255)) 711 * .build();}</pre> 712 * 713 * <p>Builder instances can be reused; it is safe to call {@link #build} multiple 714 * times to build multiple lists in series. Each new list contains all the 715 * elements of the ones created before it. 716 * 717 * @since 2.0 718 */ 719 public static final class Builder<E> extends ImmutableCollection.ArrayBasedBuilder<E> { 720 /** 721 * Creates a new builder. The returned builder is equivalent to the builder 722 * generated by {@link ImmutableList#builder}. 723 */ 724 public Builder() { 725 this(DEFAULT_INITIAL_CAPACITY); 726 } 727 728 // TODO(lowasser): consider exposing this 729 Builder(int capacity) { 730 super(capacity); 731 } 732 733 /** 734 * Adds {@code element} to the {@code ImmutableList}. 735 * 736 * @param element the element to add 737 * @return this {@code Builder} object 738 * @throws NullPointerException if {@code element} is null 739 */ 740 @CanIgnoreReturnValue 741 @Override 742 public Builder<E> add(E element) { 743 super.add(element); 744 return this; 745 } 746 747 /** 748 * Adds each element of {@code elements} to the {@code ImmutableList}. 749 * 750 * @param elements the {@code Iterable} to add to the {@code ImmutableList} 751 * @return this {@code Builder} object 752 * @throws NullPointerException if {@code elements} is null or contains a 753 * null element 754 */ 755 @CanIgnoreReturnValue 756 @Override 757 public Builder<E> addAll(Iterable<? extends E> elements) { 758 super.addAll(elements); 759 return this; 760 } 761 762 /** 763 * Adds each element of {@code elements} to the {@code ImmutableList}. 764 * 765 * @param elements the {@code Iterable} to add to the {@code ImmutableList} 766 * @return this {@code Builder} object 767 * @throws NullPointerException if {@code elements} is null or contains a 768 * null element 769 */ 770 @CanIgnoreReturnValue 771 @Override 772 public Builder<E> add(E... elements) { 773 super.add(elements); 774 return this; 775 } 776 777 /** 778 * Adds each element of {@code elements} to the {@code ImmutableList}. 779 * 780 * @param elements the {@code Iterable} to add to the {@code ImmutableList} 781 * @return this {@code Builder} object 782 * @throws NullPointerException if {@code elements} is null or contains a 783 * null element 784 */ 785 @CanIgnoreReturnValue 786 @Override 787 public Builder<E> addAll(Iterator<? extends E> elements) { 788 super.addAll(elements); 789 return this; 790 } 791 792 @CanIgnoreReturnValue 793 @Override 794 Builder<E> combine(ArrayBasedBuilder<E> builder) { 795 super.combine(builder); 796 return this; 797 } 798 799 /** 800 * Returns a newly-created {@code ImmutableList} based on the contents of 801 * the {@code Builder}. 802 */ 803 @Override 804 public ImmutableList<E> build() { 805 return asImmutableList(contents, size); 806 } 807 } 808}