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}