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
017 package com.google.common.collect;
018
019 import static com.google.common.base.Preconditions.checkNotNull;
020
021 import com.google.common.annotations.GwtCompatible;
022 import com.google.common.base.Preconditions;
023
024 import java.io.InvalidObjectException;
025 import java.io.ObjectInputStream;
026 import java.io.Serializable;
027 import java.util.ArrayList;
028 import java.util.Collection;
029 import java.util.Collections;
030 import java.util.Iterator;
031 import java.util.List;
032 import java.util.RandomAccess;
033
034 import javax.annotation.Nullable;
035
036 /**
037 * A high-performance, immutable, random-access {@code List} implementation.
038 * Does not permit null elements.
039 *
040 * <p>Unlike {@link Collections#unmodifiableList}, which is a <i>view</i> of a
041 * separate collection that can still change, an instance of {@code
042 * ImmutableList} contains its own private data and will <i>never</i> change.
043 * {@code ImmutableList} is convenient for {@code public static final} lists
044 * ("constant lists") and also lets you easily make a "defensive copy" of a list
045 * provided to your class by a caller.
046 *
047 * <p><b>Note</b>: Although this class is not final, it cannot be subclassed as
048 * it has no public or protected constructors. Thus, instances of this type are
049 * guaranteed to be immutable.
050 *
051 * @see ImmutableMap
052 * @see ImmutableSet
053 * @author Kevin Bourrillion
054 * @since 2 (imported from Google Collections Library)
055 */
056 @GwtCompatible(serializable = true, emulated = true)
057 @SuppressWarnings("serial") // we're overriding default serialization
058 public abstract class ImmutableList<E> extends ImmutableCollection<E>
059 implements List<E>, RandomAccess {
060 /**
061 * Returns the empty immutable list. This set behaves and performs comparably
062 * to {@link Collections#emptyList}, and is preferable mainly for consistency
063 * and maintainability of your code.
064 */
065 // Casting to any type is safe because the list will never hold any elements.
066 @SuppressWarnings("unchecked")
067 public static <E> ImmutableList<E> of() {
068 return (ImmutableList<E>) EmptyImmutableList.INSTANCE;
069 }
070
071 /**
072 * Returns an immutable list containing a single element. This list behaves
073 * and performs comparably to {@link Collections#singleton}, but will not
074 * accept a null element. It is preferable mainly for consistency and
075 * maintainability of your code.
076 *
077 * @throws NullPointerException if {@code element} is null
078 */
079 public static <E> ImmutableList<E> of(E element) {
080 return new SingletonImmutableList<E>(element);
081 }
082
083 /**
084 * Returns an immutable list containing the given elements, in order.
085 *
086 * @throws NullPointerException if any element is null
087 */
088 public static <E> ImmutableList<E> of(E e1, E e2) {
089 return construct(e1, e2);
090 }
091
092 /**
093 * Returns an immutable list containing the given elements, in order.
094 *
095 * @throws NullPointerException if any element is null
096 */
097 public static <E> ImmutableList<E> of(E e1, E e2, E e3) {
098 return construct(e1, e2, e3);
099 }
100
101 /**
102 * Returns an immutable list containing the given elements, in order.
103 *
104 * @throws NullPointerException if any element is null
105 */
106 public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4) {
107 return construct(e1, e2, e3, e4);
108 }
109
110 /**
111 * Returns an immutable list containing the given elements, in order.
112 *
113 * @throws NullPointerException if any element is null
114 */
115 public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5) {
116 return construct(e1, e2, e3, e4, e5);
117 }
118
119 /**
120 * Returns an immutable list containing the given elements, in order.
121 *
122 * @throws NullPointerException if any element is null
123 */
124 public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
125 return construct(e1, e2, e3, e4, e5, e6);
126 }
127
128 /**
129 * Returns an immutable list containing the given elements, in order.
130 *
131 * @throws NullPointerException if any element is null
132 */
133 public static <E> ImmutableList<E> of(
134 E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
135 return construct(e1, e2, e3, e4, e5, e6, e7);
136 }
137
138 /**
139 * Returns an immutable list containing the given elements, in order.
140 *
141 * @throws NullPointerException if any element is null
142 */
143 public static <E> ImmutableList<E> of(
144 E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
145 return construct(e1, e2, e3, e4, e5, e6, e7, e8);
146 }
147
148 /**
149 * Returns an immutable list containing the given elements, in order.
150 *
151 * @throws NullPointerException if any element is null
152 */
153 public static <E> ImmutableList<E> of(
154 E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
155 return construct(e1, e2, e3, e4, e5, e6, e7, e8, e9);
156 }
157
158 /**
159 * Returns an immutable list containing the given elements, in order.
160 *
161 * @throws NullPointerException if any element is null
162 */
163 public static <E> ImmutableList<E> of(
164 E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
165 return construct(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10);
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, E e11) {
175 return construct(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10, e11);
176 }
177
178 // These go up to eleven. After that, you just get the varargs form, and
179 // whatever warnings might come along with it. :(
180
181 /**
182 * Returns an immutable list containing the given elements, in order.
183 *
184 * @throws NullPointerException if any element is null
185 * @since 3 (source-compatible since release 2)
186 */
187 public static <E> ImmutableList<E> of(
188 E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E e11, E e12,
189 E... others) {
190 Object[] array = new Object[12 + others.length];
191 array[0] = e1;
192 array[1] = e2;
193 array[2] = e3;
194 array[3] = e4;
195 array[4] = e5;
196 array[5] = e6;
197 array[6] = e7;
198 array[7] = e8;
199 array[8] = e9;
200 array[9] = e10;
201 array[10] = e11;
202 array[11] = e12;
203 System.arraycopy(others, 0, array, 12, others.length);
204 return construct(array);
205 }
206
207 /**
208 * Returns an immutable list containing the given elements, in order.
209 *
210 * @deprecated use {@link #copyOf(Object[])}. <b>This method is scheduled for
211 * deletion in October 2011.</b>
212 * @throws NullPointerException if any of {@code elements} is null
213 * @since 2 (changed from varargs in release 3)
214 */
215 @Deprecated
216 public static <E> ImmutableList<E> of(E[] elements) {
217 return copyOf(elements);
218 }
219
220 /**
221 * Returns an immutable list containing the given elements, in order. If
222 * {@code elements} is a {@link Collection}, this method behaves exactly as
223 * {@link #copyOf(Collection)}; otherwise, it behaves exactly as {@code
224 * copyOf(elements.iterator()}.
225 *
226 * @throws NullPointerException if any of {@code elements} is null
227 */
228 public static <E> ImmutableList<E> copyOf(Iterable<? extends E> elements) {
229 checkNotNull(elements); // TODO(kevinb): is this here only for GWT?
230 return (elements instanceof Collection)
231 ? copyOf(Collections2.cast(elements))
232 : copyOf(elements.iterator());
233 }
234
235 /**
236 * Returns an immutable list containing the given elements, in order.
237 *
238 * <p>Despite the method name, this method attempts to avoid actually copying
239 * the data when it is safe to do so. The exact circumstances under which a
240 * copy will or will not be performed are undocumented and subject to change.
241 *
242 * <p>Note that if {@code list} is a {@code List<String>}, then {@code
243 * ImmutableList.copyOf(list)} returns an {@code ImmutableList<String>}
244 * containing each of the strings in {@code list}, while
245 * ImmutableList.of(list)} returns an {@code ImmutableList<List<String>>}
246 * containing one element (the given list itself).
247 *
248 * <p>This method is safe to use even when {@code elements} is a synchronized
249 * or concurrent collection that is currently being modified by another
250 * thread.
251 *
252 * @throws NullPointerException if any of {@code elements} is null
253 */
254 public static <E> ImmutableList<E> copyOf(Collection<? extends E> elements) {
255 if (elements instanceof ImmutableCollection) {
256 @SuppressWarnings("unchecked") // all supported methods are covariant
257 ImmutableList<E> list = ((ImmutableCollection<E>) elements).asList();
258 return list.isPartialView() ? copyFromCollection(list) : list;
259 }
260 return copyFromCollection(elements);
261 }
262
263 /**
264 * Returns an immutable list containing the given elements, in order.
265 *
266 * @throws NullPointerException if any of {@code elements} is null
267 */
268 public static <E> ImmutableList<E> copyOf(Iterator<? extends E> elements) {
269 return copyFromCollection(Lists.newArrayList(elements));
270 }
271
272 /**
273 * Returns an immutable list containing the given elements, in order.
274 *
275 * @throws NullPointerException if any of {@code elements} is null
276 * @since 3
277 */
278 public static <E> ImmutableList<E> copyOf(E[] elements) {
279 switch (elements.length) {
280 case 0:
281 return ImmutableList.of();
282 case 1:
283 return new SingletonImmutableList<E>(elements[0]);
284 default:
285 return construct(elements.clone());
286 }
287 }
288
289 private static <E> ImmutableList<E> copyFromCollection(
290 Collection<? extends E> collection) {
291 Object[] elements = collection.toArray();
292 switch (elements.length) {
293 case 0:
294 return of();
295 case 1:
296 @SuppressWarnings("unchecked") // collection had only Es in it
297 ImmutableList<E> list = new SingletonImmutableList<E>((E) elements[0]);
298 return list;
299 default:
300 // safe to use the array without copying it
301 // as specified by Collection.toArray().
302 return construct(elements);
303 }
304 }
305
306 /** {@code elements} has to be internally created array. */
307 private static <E> ImmutableList<E> construct(Object... elements) {
308 for (int i = 0; i < elements.length; i++) {
309 checkElementNotNull(elements[i], i);
310 }
311 return new RegularImmutableList<E>(elements);
312 }
313
314 // We do this instead of Preconditions.checkNotNull to save boxing and array
315 // creation cost.
316 private static Object checkElementNotNull(Object element, int index) {
317 if (element == null) {
318 throw new NullPointerException("at index " + index);
319 }
320 return element;
321 }
322
323 ImmutableList() {}
324
325 // This declaration is needed to make List.iterator() and
326 // ImmutableCollection.iterator() consistent.
327 @Override public UnmodifiableIterator<E> iterator() {
328 return listIterator();
329 }
330
331 @Override public UnmodifiableListIterator<E> listIterator() {
332 return listIterator(0);
333 }
334
335 @Override public abstract UnmodifiableListIterator<E> listIterator(int index);
336
337 // Mark these two methods with @Nullable
338
339 @Override
340 public abstract int indexOf(@Nullable Object object);
341
342 @Override
343 public abstract int lastIndexOf(@Nullable Object object);
344
345 // constrain the return type to ImmutableList<E>
346
347 /**
348 * Returns an immutable list of the elements between the specified {@code
349 * fromIndex}, inclusive, and {@code toIndex}, exclusive. (If {@code
350 * fromIndex} and {@code toIndex} are equal, the empty immutable list is
351 * returned.)
352 */
353 @Override
354 public abstract ImmutableList<E> subList(int fromIndex, int toIndex);
355
356 /**
357 * Guaranteed to throw an exception and leave the list unmodified.
358 *
359 * @throws UnsupportedOperationException always
360 */
361 @Override
362 public final boolean addAll(int index, Collection<? extends E> newElements) {
363 throw new UnsupportedOperationException();
364 }
365
366 /**
367 * Guaranteed to throw an exception and leave the list unmodified.
368 *
369 * @throws UnsupportedOperationException always
370 */
371 @Override
372 public final E set(int index, E element) {
373 throw new UnsupportedOperationException();
374 }
375
376 /**
377 * Guaranteed to throw an exception and leave the list unmodified.
378 *
379 * @throws UnsupportedOperationException always
380 */
381 @Override
382 public final void add(int index, E element) {
383 throw new UnsupportedOperationException();
384 }
385
386 /**
387 * Guaranteed to throw an exception and leave the list unmodified.
388 *
389 * @throws UnsupportedOperationException always
390 */
391 @Override
392 public final E remove(int index) {
393 throw new UnsupportedOperationException();
394 }
395
396 /**
397 * Returns this list instance.
398 *
399 * @since 2
400 */
401 @Override public ImmutableList<E> asList() {
402 return this;
403 }
404
405 /**
406 * Returns a view of this immutable list in reverse order. For example, {@code
407 * ImmutableList.of(1, 2, 3).reverse()} is equivalent to {@code
408 * ImmutableList.of(3, 2, 1)}.
409 *
410 * @return a view of this immutable list in reverse order
411 * @since 7
412 */
413 public ImmutableList<E> reverse() {
414 return new ReverseImmutableList<E>(this);
415 }
416
417 private static class ReverseImmutableList<E> extends ImmutableList<E> {
418 private transient final ImmutableList<E> forwardList;
419 private transient final int size;
420
421 ReverseImmutableList(ImmutableList<E> backingList) {
422 this.forwardList = backingList;
423 this.size = backingList.size();
424 }
425
426 private int reverseIndex(int index) {
427 return (size - 1) - index;
428 }
429
430 private int reversePosition(int index) {
431 return size - index;
432 }
433
434 @Override public ImmutableList<E> reverse() {
435 return forwardList;
436 }
437
438 @Override public boolean contains(@Nullable Object object) {
439 return forwardList.contains(object);
440 }
441
442 @Override public boolean containsAll(Collection<?> targets) {
443 return forwardList.containsAll(targets);
444 }
445
446 @Override public int indexOf(@Nullable Object object) {
447 int index = forwardList.lastIndexOf(object);
448 return (index >= 0) ? reverseIndex(index) : -1;
449 }
450
451 @Override public int lastIndexOf(@Nullable Object object) {
452 int index = forwardList.indexOf(object);
453 return (index >= 0) ? reverseIndex(index) : -1;
454 }
455
456 @Override public ImmutableList<E> subList(int fromIndex, int toIndex) {
457 Preconditions.checkPositionIndexes(fromIndex, toIndex, size);
458 return forwardList.subList(
459 reversePosition(toIndex), reversePosition(fromIndex)).reverse();
460 }
461
462 @Override public E get(int index) {
463 Preconditions.checkElementIndex(index, size);
464 return forwardList.get(reverseIndex(index));
465 }
466
467 @Override public UnmodifiableListIterator<E> listIterator(int index) {
468 Preconditions.checkPositionIndex(index, size);
469 final UnmodifiableListIterator<E> forward =
470 forwardList.listIterator(reversePosition(index));
471 return new UnmodifiableListIterator<E>() {
472 @Override public boolean hasNext() {
473 return forward.hasPrevious();
474 }
475
476 @Override public boolean hasPrevious() {
477 return forward.hasNext();
478 }
479
480 @Override public E next() {
481 return forward.previous();
482 }
483
484 @Override public int nextIndex() {
485 return reverseIndex(forward.previousIndex());
486 }
487
488 @Override public E previous() {
489 return forward.next();
490 }
491
492 @Override public int previousIndex() {
493 return reverseIndex(forward.nextIndex());
494 }
495 };
496 }
497
498 @Override public int size() {
499 return size;
500 }
501
502 @Override public boolean isEmpty() {
503 return forwardList.isEmpty();
504 }
505
506 @Override boolean isPartialView() {
507 return forwardList.isPartialView();
508 }
509 }
510
511 @Override public boolean equals(Object obj) {
512 return Lists.equalsImpl(this, obj);
513 }
514
515 @Override public int hashCode() {
516 return Lists.hashCodeImpl(this);
517 }
518
519 /*
520 * Serializes ImmutableLists as their logical contents. This ensures that
521 * implementation types do not leak into the serialized representation.
522 */
523 private static class SerializedForm implements Serializable {
524 final Object[] elements;
525 SerializedForm(Object[] elements) {
526 this.elements = elements;
527 }
528 Object readResolve() {
529 return copyOf(elements);
530 }
531 private static final long serialVersionUID = 0;
532 }
533
534 private void readObject(ObjectInputStream stream)
535 throws InvalidObjectException {
536 throw new InvalidObjectException("Use SerializedForm");
537 }
538
539 @Override Object writeReplace() {
540 return new SerializedForm(toArray());
541 }
542
543 /**
544 * Returns a new builder. The generated builder is equivalent to the builder
545 * created by the {@link Builder} constructor.
546 */
547 public static <E> Builder<E> builder() {
548 return new Builder<E>();
549 }
550
551 /**
552 * A builder for creating immutable list instances, especially {@code public
553 * static final} lists ("constant lists"). Example: <pre> {@code
554 *
555 * public static final ImmutableList<Color> GOOGLE_COLORS
556 * = new ImmutableList.Builder<Color>()
557 * .addAll(WEBSAFE_COLORS)
558 * .add(new Color(0, 191, 255))
559 * .build();}</pre>
560 *
561 * Builder instances can be reused; it is safe to call {@link #build} multiple
562 * times to build multiple lists in series. Each new list contains all the
563 * elements of the ones created before it.
564 *
565 * @since 2 (imported from Google Collections Library)
566 */
567 public static final class Builder<E> extends ImmutableCollection.Builder<E> {
568 private final ArrayList<E> contents = Lists.newArrayList();
569
570 /**
571 * Creates a new builder. The returned builder is equivalent to the builder
572 * generated by {@link ImmutableList#builder}.
573 */
574 public Builder() {}
575
576 /**
577 * Adds {@code element} to the {@code ImmutableList}.
578 *
579 * @param element the element to add
580 * @return this {@code Builder} object
581 * @throws NullPointerException if {@code element} is null
582 */
583 @Override public Builder<E> add(E element) {
584 contents.add(checkNotNull(element));
585 return this;
586 }
587
588 /**
589 * Adds each element of {@code elements} to the {@code ImmutableList}.
590 *
591 * @param elements the {@code Iterable} to add to the {@code ImmutableList}
592 * @return this {@code Builder} object
593 * @throws NullPointerException if {@code elements} is null or contains a
594 * null element
595 */
596 @Override public Builder<E> addAll(Iterable<? extends E> elements) {
597 if (elements instanceof Collection) {
598 Collection<?> collection = (Collection<?>) elements;
599 contents.ensureCapacity(contents.size() + collection.size());
600 }
601 super.addAll(elements);
602 return this;
603 }
604
605 /**
606 * Adds each element of {@code elements} to the {@code ImmutableList}.
607 *
608 * @param elements the {@code Iterable} to add to the {@code ImmutableList}
609 * @return this {@code Builder} object
610 * @throws NullPointerException if {@code elements} is null or contains a
611 * null element
612 */
613 @Override public Builder<E> add(E... elements) {
614 contents.ensureCapacity(contents.size() + elements.length);
615 super.add(elements);
616 return this;
617 }
618
619 /**
620 * Adds each element of {@code elements} to the {@code ImmutableList}.
621 *
622 * @param elements the {@code Iterable} to add to the {@code ImmutableList}
623 * @return this {@code Builder} object
624 * @throws NullPointerException if {@code elements} is null or contains a
625 * null element
626 */
627 @Override public Builder<E> addAll(Iterator<? extends E> elements) {
628 super.addAll(elements);
629 return this;
630 }
631
632 /**
633 * Returns a newly-created {@code ImmutableList} based on the contents of
634 * the {@code Builder}.
635 */
636 @Override public ImmutableList<E> build() {
637 return copyOf(contents);
638 }
639 }
640 }