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