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 new SingletonImmutableList<E>(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    switch (elements.length) {
286      case 0:
287        return ImmutableList.of();
288      case 1:
289        return new SingletonImmutableList<E>(elements[0]);
290      default:
291        return new RegularImmutableList<E>(checkElementsNotNull(elements.clone()));
292    }
293  }
294
295  /**
296   * Returns an immutable list containing the given elements, sorted according to their natural
297   * order. The sorting algorithm used is stable, so elements that compare as equal will stay in the
298   * order in which they appear in the input.
299   *
300   * <p>If your data has no duplicates, or you wish to deduplicate elements, use {@code
301   * ImmutableSortedSet.copyOf(elements)}; if you want a {@code List} you can use its {@code
302   * asList()} view.
303   *
304   * <p><b>Java 8 users:</b> If you want to convert a {@link java.util.stream.Stream} to a sorted
305   * {@code ImmutableList}, use {@code stream.sorted().collect(toImmutableList())}.
306   *
307   * @throws NullPointerException if any element in the input is null
308   * @since 21.0
309   */
310  public static <E extends Comparable<? super E>> ImmutableList<E> sortedCopyOf(
311      Iterable<? extends E> elements) {
312    Comparable[] array = Iterables.toArray(elements, new Comparable[0]);
313    checkElementsNotNull(array);
314    Arrays.sort(array);
315    return asImmutableList(array);
316  }
317
318  /**
319   * Returns an immutable list containing the given elements, in sorted order relative to the
320   * specified comparator. The sorting algorithm used is stable, so elements that compare as equal
321   * will stay in the order in which they appear in the input.
322   *
323   * <p>If your data has no duplicates, or you wish to deduplicate elements, use {@code
324   * ImmutableSortedSet.copyOf(comparator, elements)}; if you want a {@code List} you can use its
325   * {@code asList()} view.
326   *
327   * <p><b>Java 8 users:</b> If you want to convert a {@link java.util.stream.Stream} to a sorted
328   * {@code ImmutableList}, use {@code stream.sorted(comparator).collect(toImmutableList())}.
329   *
330   * @throws NullPointerException if any element in the input is null
331   * @since 21.0
332   */
333  public static <E> ImmutableList<E> sortedCopyOf(
334      Comparator<? super E> comparator, Iterable<? extends E> elements) {
335    checkNotNull(comparator);
336    @SuppressWarnings("unchecked") // all supported methods are covariant
337    E[] array = (E[]) Iterables.toArray(elements);
338    checkElementsNotNull(array);
339    Arrays.sort(array, comparator);
340    return asImmutableList(array);
341  }
342
343  /**
344   * Views the array as an immutable list.  Checks for nulls; does not copy.
345   */
346  private static <E> ImmutableList<E> construct(Object... elements) {
347    return asImmutableList(checkElementsNotNull(elements));
348  }
349
350  /**
351   * Views the array as an immutable list.  Does not check for nulls; does not copy.
352   *
353   * <p>The array must be internally created.
354   */
355  static <E> ImmutableList<E> asImmutableList(Object[] elements) {
356    return asImmutableList(elements, elements.length);
357  }
358
359  /**
360   * Views the array as an immutable list. Copies if the specified range does not cover the complete
361   * array. Does not check for nulls.
362   */
363  static <E> ImmutableList<E> asImmutableList(Object[] elements, int length) {
364    switch (length) {
365      case 0:
366        return of();
367      case 1:
368        @SuppressWarnings("unchecked") // collection had only Es in it
369        ImmutableList<E> list = new SingletonImmutableList<E>((E) elements[0]);
370        return list;
371      default:
372        if (length < elements.length) {
373          elements = Arrays.copyOf(elements, length);
374        }
375        return new RegularImmutableList<E>(elements);
376    }
377  }
378
379  ImmutableList() {}
380
381  // This declaration is needed to make List.iterator() and
382  // ImmutableCollection.iterator() consistent.
383  @Override
384  public UnmodifiableIterator<E> iterator() {
385    return listIterator();
386  }
387
388  @Override
389  public UnmodifiableListIterator<E> listIterator() {
390    return listIterator(0);
391  }
392
393  @Override
394  public UnmodifiableListIterator<E> listIterator(int index) {
395    return new AbstractIndexedListIterator<E>(size(), index) {
396      @Override
397      protected E get(int index) {
398        return ImmutableList.this.get(index);
399      }
400    };
401  }
402
403  @Override
404  public void forEach(Consumer<? super E> consumer) {
405    checkNotNull(consumer);
406    int n = size();
407    for (int i = 0; i < n; i++) {
408      consumer.accept(get(i));
409    }
410  }
411
412  @Override
413  public int indexOf(@Nullable Object object) {
414    return (object == null) ? -1 : Lists.indexOfImpl(this, object);
415  }
416
417  @Override
418  public int lastIndexOf(@Nullable Object object) {
419    return (object == null) ? -1 : Lists.lastIndexOfImpl(this, object);
420  }
421
422  @Override
423  public boolean contains(@Nullable Object object) {
424    return indexOf(object) >= 0;
425  }
426
427  // constrain the return type to ImmutableList<E>
428
429  /**
430   * Returns an immutable list of the elements between the specified {@code
431   * fromIndex}, inclusive, and {@code toIndex}, exclusive. (If {@code
432   * fromIndex} and {@code toIndex} are equal, the empty immutable list is
433   * returned.)
434   */
435  @Override
436  public ImmutableList<E> subList(int fromIndex, int toIndex) {
437    checkPositionIndexes(fromIndex, toIndex, size());
438    int length = toIndex - fromIndex;
439    if (length == size()) {
440      return this;
441    }
442    switch (length) {
443      case 0:
444        return of();
445      case 1:
446        return of(get(fromIndex));
447      default:
448        return subListUnchecked(fromIndex, toIndex);
449    }
450  }
451
452  /**
453   * Called by the default implementation of {@link #subList} when {@code
454   * toIndex - fromIndex > 1}, after index validation has already been
455   * performed.
456   */
457  ImmutableList<E> subListUnchecked(int fromIndex, int toIndex) {
458    return new SubList(fromIndex, toIndex - fromIndex);
459  }
460
461  class SubList extends ImmutableList<E> {
462    final transient int offset;
463    final transient int length;
464
465    SubList(int offset, int length) {
466      this.offset = offset;
467      this.length = length;
468    }
469
470    @Override
471    public int size() {
472      return length;
473    }
474
475    @Override
476    public E get(int index) {
477      checkElementIndex(index, length);
478      return ImmutableList.this.get(index + offset);
479    }
480
481    @Override
482    public ImmutableList<E> subList(int fromIndex, int toIndex) {
483      checkPositionIndexes(fromIndex, toIndex, length);
484      return ImmutableList.this.subList(fromIndex + offset, toIndex + offset);
485    }
486
487    @Override
488    boolean isPartialView() {
489      return true;
490    }
491  }
492
493  /**
494   * Guaranteed to throw an exception and leave the list unmodified.
495   *
496   * @throws UnsupportedOperationException always
497   * @deprecated Unsupported operation.
498   */
499  @CanIgnoreReturnValue
500  @Deprecated
501  @Override
502  public final boolean addAll(int index, Collection<? extends E> newElements) {
503    throw new UnsupportedOperationException();
504  }
505
506  /**
507   * Guaranteed to throw an exception and leave the list unmodified.
508   *
509   * @throws UnsupportedOperationException always
510   * @deprecated Unsupported operation.
511   */
512  @CanIgnoreReturnValue
513  @Deprecated
514  @Override
515  public final E set(int index, E element) {
516    throw new UnsupportedOperationException();
517  }
518
519  /**
520   * Guaranteed to throw an exception and leave the list unmodified.
521   *
522   * @throws UnsupportedOperationException always
523   * @deprecated Unsupported operation.
524   */
525  @Deprecated
526  @Override
527  public final void add(int index, E element) {
528    throw new UnsupportedOperationException();
529  }
530
531  /**
532   * Guaranteed to throw an exception and leave the list unmodified.
533   *
534   * @throws UnsupportedOperationException always
535   * @deprecated Unsupported operation.
536   */
537  @CanIgnoreReturnValue
538  @Deprecated
539  @Override
540  public final E remove(int index) {
541    throw new UnsupportedOperationException();
542  }
543
544  /**
545   * Guaranteed to throw an exception and leave the list unmodified.
546   *
547   * @throws UnsupportedOperationException always
548   * @deprecated Unsupported operation.
549   */
550  @Deprecated
551  @Override
552  public final void replaceAll(UnaryOperator<E> operator) {
553    throw new UnsupportedOperationException();
554  }
555
556  /**
557   * Guaranteed to throw an exception and leave the list unmodified.
558   *
559   * @throws UnsupportedOperationException always
560   * @deprecated Unsupported operation.
561   */
562  @Deprecated
563  @Override
564  public final void sort(Comparator<? super E> c) {
565    throw new UnsupportedOperationException();
566  }
567
568  /**
569   * Returns this list instance.
570   *
571   * @since 2.0
572   */
573  @Override
574  public final ImmutableList<E> asList() {
575    return this;
576  }
577
578  @Override
579  public Spliterator<E> spliterator() {
580    return CollectSpliterators.indexed(size(), SPLITERATOR_CHARACTERISTICS, this::get);
581  }
582
583  @Override
584  int copyIntoArray(Object[] dst, int offset) {
585    // this loop is faster for RandomAccess instances, which ImmutableLists are
586    int size = size();
587    for (int i = 0; i < size; i++) {
588      dst[offset + i] = get(i);
589    }
590    return offset + size;
591  }
592
593  /**
594   * Returns a view of this immutable list in reverse order. For example, {@code
595   * ImmutableList.of(1, 2, 3).reverse()} is equivalent to {@code
596   * ImmutableList.of(3, 2, 1)}.
597   *
598   * @return a view of this immutable list in reverse order
599   * @since 7.0
600   */
601  public ImmutableList<E> reverse() {
602    return (size() <= 1) ? this : new ReverseImmutableList<E>(this);
603  }
604
605  private static class ReverseImmutableList<E> extends ImmutableList<E> {
606    private final transient ImmutableList<E> forwardList;
607
608    ReverseImmutableList(ImmutableList<E> backingList) {
609      this.forwardList = backingList;
610    }
611
612    private int reverseIndex(int index) {
613      return (size() - 1) - index;
614    }
615
616    private int reversePosition(int index) {
617      return size() - index;
618    }
619
620    @Override
621    public ImmutableList<E> reverse() {
622      return forwardList;
623    }
624
625    @Override
626    public boolean contains(@Nullable Object object) {
627      return forwardList.contains(object);
628    }
629
630    @Override
631    public int indexOf(@Nullable Object object) {
632      int index = forwardList.lastIndexOf(object);
633      return (index >= 0) ? reverseIndex(index) : -1;
634    }
635
636    @Override
637    public int lastIndexOf(@Nullable Object object) {
638      int index = forwardList.indexOf(object);
639      return (index >= 0) ? reverseIndex(index) : -1;
640    }
641
642    @Override
643    public ImmutableList<E> subList(int fromIndex, int toIndex) {
644      checkPositionIndexes(fromIndex, toIndex, size());
645      return forwardList.subList(reversePosition(toIndex), reversePosition(fromIndex)).reverse();
646    }
647
648    @Override
649    public E get(int index) {
650      checkElementIndex(index, size());
651      return forwardList.get(reverseIndex(index));
652    }
653
654    @Override
655    public int size() {
656      return forwardList.size();
657    }
658
659    @Override
660    boolean isPartialView() {
661      return forwardList.isPartialView();
662    }
663  }
664
665  @Override
666  public boolean equals(@Nullable Object obj) {
667    return Lists.equalsImpl(this, obj);
668  }
669
670  @Override
671  public int hashCode() {
672    int hashCode = 1;
673    int n = size();
674    for (int i = 0; i < n; i++) {
675      hashCode = 31 * hashCode + get(i).hashCode();
676
677      hashCode = ~~hashCode;
678      // needed to deal with GWT integer overflow
679    }
680    return hashCode;
681  }
682
683  /*
684   * Serializes ImmutableLists as their logical contents. This ensures that
685   * implementation types do not leak into the serialized representation.
686   */
687  static class SerializedForm implements Serializable {
688    final Object[] elements;
689
690    SerializedForm(Object[] elements) {
691      this.elements = elements;
692    }
693
694    Object readResolve() {
695      return copyOf(elements);
696    }
697
698    private static final long serialVersionUID = 0;
699  }
700
701  private void readObject(ObjectInputStream stream) throws InvalidObjectException {
702    throw new InvalidObjectException("Use SerializedForm");
703  }
704
705  @Override
706  Object writeReplace() {
707    return new SerializedForm(toArray());
708  }
709
710  /**
711   * Returns a new builder. The generated builder is equivalent to the builder
712   * created by the {@link Builder} constructor.
713   */
714  public static <E> Builder<E> builder() {
715    return new Builder<E>();
716  }
717
718  /**
719   * A builder for creating immutable list instances, especially {@code public
720   * static final} lists ("constant lists"). Example: <pre>   {@code
721   *
722   *   public static final ImmutableList<Color> GOOGLE_COLORS
723   *       = new ImmutableList.Builder<Color>()
724   *           .addAll(WEBSAFE_COLORS)
725   *           .add(new Color(0, 191, 255))
726   *           .build();}</pre>
727   *
728   * <p>Builder instances can be reused; it is safe to call {@link #build} multiple
729   * times to build multiple lists in series. Each new list contains all the
730   * elements of the ones created before it.
731   *
732   * @since 2.0
733   */
734  public static final class Builder<E> extends ImmutableCollection.ArrayBasedBuilder<E> {
735    /**
736     * Creates a new builder. The returned builder is equivalent to the builder
737     * generated by {@link ImmutableList#builder}.
738     */
739    public Builder() {
740      this(DEFAULT_INITIAL_CAPACITY);
741    }
742
743    // TODO(lowasser): consider exposing this
744    Builder(int capacity) {
745      super(capacity);
746    }
747
748    /**
749     * Adds {@code element} to the {@code ImmutableList}.
750     *
751     * @param element the element to add
752     * @return this {@code Builder} object
753     * @throws NullPointerException if {@code element} is null
754     */
755    @CanIgnoreReturnValue
756    @Override
757    public Builder<E> add(E element) {
758      super.add(element);
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> addAll(Iterable<? extends E> elements) {
773      super.addAll(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> add(E... elements) {
788      super.add(elements);
789      return this;
790    }
791
792    /**
793     * Adds each element of {@code elements} to the {@code ImmutableList}.
794     *
795     * @param elements the {@code Iterable} to add to the {@code ImmutableList}
796     * @return this {@code Builder} object
797     * @throws NullPointerException if {@code elements} is null or contains a
798     *     null element
799     */
800    @CanIgnoreReturnValue
801    @Override
802    public Builder<E> addAll(Iterator<? extends E> elements) {
803      super.addAll(elements);
804      return this;
805    }
806
807    @CanIgnoreReturnValue
808    @Override
809    Builder<E> combine(ArrayBasedBuilder<E> builder) {
810      super.combine(builder);
811      return this;
812    }
813
814    /**
815     * Returns a newly-created {@code ImmutableList} based on the contents of
816     * the {@code Builder}.
817     */
818    @Override
819    public ImmutableList<E> build() {
820      return asImmutableList(contents, size);
821    }
822  }
823}