All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.collect.ImmutableList Maven / Gradle / Ivy

There is a newer version: 1.5.7
Show newest version
/*
 * Copyright (C) 2007 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.collect;

import static com.google.common.base.Preconditions.checkElementIndex;
import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.base.Preconditions.checkPositionIndexes;
import static com.google.common.collect.ObjectArrays.arraysCopyOf;
import static com.google.common.collect.ObjectArrays.checkElementsNotNull;

import com.google.common.annotations.GwtCompatible;

import java.io.InvalidObjectException;
import java.io.ObjectInputStream;
import java.io.Serializable;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.RandomAccess;

import javax.annotation.Nullable;

/**
 * A high-performance, immutable, random-access {@code List} implementation.
 * Does not permit null elements.
 *
 * 

Unlike {@link Collections#unmodifiableList}, which is a view of a * separate collection that can still change, an instance of {@code * ImmutableList} contains its own private data and will never change. * {@code ImmutableList} is convenient for {@code public static final} lists * ("constant lists") and also lets you easily make a "defensive copy" of a list * provided to your class by a caller. * *

Note: Although this class is not final, it cannot be subclassed as * it has no public or protected constructors. Thus, instances of this type are * guaranteed to be immutable. * *

See the Guava User Guide article on * immutable collections. * * @see ImmutableMap * @see ImmutableSet * @author Kevin Bourrillion * @since 2.0 (imported from Google Collections Library) */ @GwtCompatible(serializable = true, emulated = true) @SuppressWarnings("serial") // we're overriding default serialization public abstract class ImmutableList extends ImmutableCollection implements List, RandomAccess { private static final ImmutableList EMPTY = new RegularImmutableList(ObjectArrays.EMPTY_ARRAY); /** * Returns the empty immutable list. This set behaves and performs comparably * to {@link Collections#emptyList}, and is preferable mainly for consistency * and maintainability of your code. */ // Casting to any type is safe because the list will never hold any elements. @SuppressWarnings("unchecked") public static ImmutableList of() { return (ImmutableList) EMPTY; } /** * Returns an immutable list containing a single element. This list behaves * and performs comparably to {@link Collections#singleton}, but will not * accept a null element. It is preferable mainly for consistency and * maintainability of your code. * * @throws NullPointerException if {@code element} is null */ public static ImmutableList of(E element) { return new SingletonImmutableList(element); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of(E e1, E e2) { return construct(e1, e2); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of(E e1, E e2, E e3) { return construct(e1, e2, e3); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of(E e1, E e2, E e3, E e4) { return construct(e1, e2, e3, e4); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of(E e1, E e2, E e3, E e4, E e5) { return construct(e1, e2, e3, e4, e5); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of(E e1, E e2, E e3, E e4, E e5, E e6) { return construct(e1, e2, e3, e4, e5, e6); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of( E e1, E e2, E e3, E e4, E e5, E e6, E e7) { return construct(e1, e2, e3, e4, e5, e6, e7); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of( E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) { return construct(e1, e2, e3, e4, e5, e6, e7, e8); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of( E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) { return construct(e1, e2, e3, e4, e5, e6, e7, e8, e9); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of( E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) { return construct(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null */ public static ImmutableList of( E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E e11) { return construct(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10, e11); } // These go up to eleven. After that, you just get the varargs form, and // whatever warnings might come along with it. :( /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any element is null * @since 3.0 (source-compatible since 2.0) */ public static ImmutableList of( 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) { Object[] array = new Object[12 + others.length]; array[0] = e1; array[1] = e2; array[2] = e3; array[3] = e4; array[4] = e5; array[5] = e6; array[6] = e7; array[7] = e8; array[8] = e9; array[9] = e10; array[10] = e11; array[11] = e12; System.arraycopy(others, 0, array, 12, others.length); return construct(array); } /** * Returns an immutable list containing the given elements, in order. If * {@code elements} is a {@link Collection}, this method behaves exactly as * {@link #copyOf(Collection)}; otherwise, it behaves exactly as {@code * copyOf(elements.iterator()}. * * @throws NullPointerException if any of {@code elements} is null */ public static ImmutableList copyOf(Iterable elements) { checkNotNull(elements); // TODO(kevinb): is this here only for GWT? return (elements instanceof Collection) ? copyOf((Collection) elements) : copyOf(elements.iterator()); } /** * Returns an immutable list containing the given elements, in order. * *

Despite the method name, this method attempts to avoid actually copying * the data when it is safe to do so. The exact circumstances under which a * copy will or will not be performed are undocumented and subject to change. * *

Note that if {@code list} is a {@code List}, then {@code * ImmutableList.copyOf(list)} returns an {@code ImmutableList} * containing each of the strings in {@code list}, while * ImmutableList.of(list)} returns an {@code ImmutableList>} * containing one element (the given list itself). * *

This method is safe to use even when {@code elements} is a synchronized * or concurrent collection that is currently being modified by another * thread. * * @throws NullPointerException if any of {@code elements} is null */ public static ImmutableList copyOf(Collection elements) { if (elements instanceof ImmutableCollection) { @SuppressWarnings("unchecked") // all supported methods are covariant ImmutableList list = ((ImmutableCollection) elements).asList(); return list.isPartialView() ? ImmutableList.asImmutableList(list.toArray()) : list; } return construct(elements.toArray()); } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any of {@code elements} is null */ public static ImmutableList copyOf(Iterator elements) { // We special-case for 0 or 1 elements, but going further is madness. if (!elements.hasNext()) { return of(); } E first = elements.next(); if (!elements.hasNext()) { return of(first); } else { return new ImmutableList.Builder() .add(first) .addAll(elements) .build(); } } /** * Returns an immutable list containing the given elements, in order. * * @throws NullPointerException if any of {@code elements} is null * @since 3.0 */ public static ImmutableList copyOf(E[] elements) { switch (elements.length) { case 0: return ImmutableList.of(); case 1: return new SingletonImmutableList(elements[0]); default: return new RegularImmutableList(checkElementsNotNull(elements.clone())); } } /** * Views the array as an immutable list. Checks for nulls; does not copy. */ private static ImmutableList construct(Object... elements) { return asImmutableList(checkElementsNotNull(elements)); } /** * Views the array as an immutable list. Does not check for nulls; does not copy. * *

The array must be internally created. */ static ImmutableList asImmutableList(Object[] elements) { return asImmutableList(elements, elements.length); } /** * Views the array as an immutable list. Copies if the specified range does not cover the complete * array. Does not check for nulls. */ static ImmutableList asImmutableList(Object[] elements, int length) { switch (length) { case 0: return of(); case 1: @SuppressWarnings("unchecked") // collection had only Es in it ImmutableList list = new SingletonImmutableList((E) elements[0]); return list; default: if (length < elements.length) { elements = arraysCopyOf(elements, length); } return new RegularImmutableList(elements); } } ImmutableList() {} // This declaration is needed to make List.iterator() and // ImmutableCollection.iterator() consistent. @Override public UnmodifiableIterator iterator() { return listIterator(); } @Override public UnmodifiableListIterator listIterator() { return listIterator(0); } @Override public UnmodifiableListIterator listIterator(int index) { return new AbstractIndexedListIterator(size(), index) { @Override protected E get(int index) { return ImmutableList.this.get(index); } }; } @Override public int indexOf(@Nullable Object object) { return (object == null) ? -1 : Lists.indexOfImpl(this, object); } @Override public int lastIndexOf(@Nullable Object object) { return (object == null) ? -1 : Lists.lastIndexOfImpl(this, object); } @Override public boolean contains(@Nullable Object object) { return indexOf(object) >= 0; } // constrain the return type to ImmutableList /** * Returns an immutable list of the elements between the specified {@code * fromIndex}, inclusive, and {@code toIndex}, exclusive. (If {@code * fromIndex} and {@code toIndex} are equal, the empty immutable list is * returned.) */ @Override public ImmutableList subList(int fromIndex, int toIndex) { checkPositionIndexes(fromIndex, toIndex, size()); int length = toIndex - fromIndex; switch (length) { case 0: return of(); case 1: return of(get(fromIndex)); default: return subListUnchecked(fromIndex, toIndex); } } /** * Called by the default implementation of {@link #subList} when {@code * toIndex - fromIndex > 1}, after index validation has already been * performed. */ ImmutableList subListUnchecked(int fromIndex, int toIndex) { return new SubList(fromIndex, toIndex - fromIndex); } class SubList extends ImmutableList { transient final int offset; transient final int length; SubList(int offset, int length) { this.offset = offset; this.length = length; } @Override public int size() { return length; } @Override public E get(int index) { checkElementIndex(index, length); return ImmutableList.this.get(index + offset); } @Override public ImmutableList subList(int fromIndex, int toIndex) { checkPositionIndexes(fromIndex, toIndex, length); return ImmutableList.this.subList(fromIndex + offset, toIndex + offset); } @Override boolean isPartialView() { return true; } } /** * Guaranteed to throw an exception and leave the list unmodified. * * @throws UnsupportedOperationException always * @deprecated Unsupported operation. */ @Deprecated @Override public final boolean addAll(int index, Collection newElements) { throw new UnsupportedOperationException(); } /** * Guaranteed to throw an exception and leave the list unmodified. * * @throws UnsupportedOperationException always * @deprecated Unsupported operation. */ @Deprecated @Override public final E set(int index, E element) { throw new UnsupportedOperationException(); } /** * Guaranteed to throw an exception and leave the list unmodified. * * @throws UnsupportedOperationException always * @deprecated Unsupported operation. */ @Deprecated @Override public final void add(int index, E element) { throw new UnsupportedOperationException(); } /** * Guaranteed to throw an exception and leave the list unmodified. * * @throws UnsupportedOperationException always * @deprecated Unsupported operation. */ @Deprecated @Override public final E remove(int index) { throw new UnsupportedOperationException(); } /** * Returns this list instance. * * @since 2.0 */ @Override public final ImmutableList asList() { return this; } @Override int copyIntoArray(Object[] dst, int offset) { // this loop is faster for RandomAccess instances, which ImmutableLists are int size = size(); for (int i = 0; i < size; i++) { dst[offset + i] = get(i); } return offset + size; } /** * Returns a view of this immutable list in reverse order. For example, {@code * ImmutableList.of(1, 2, 3).reverse()} is equivalent to {@code * ImmutableList.of(3, 2, 1)}. * * @return a view of this immutable list in reverse order * @since 7.0 */ public ImmutableList reverse() { return new ReverseImmutableList(this); } private static class ReverseImmutableList extends ImmutableList { private final transient ImmutableList forwardList; ReverseImmutableList(ImmutableList backingList) { this.forwardList = backingList; } private int reverseIndex(int index) { return (size() - 1) - index; } private int reversePosition(int index) { return size() - index; } @Override public ImmutableList reverse() { return forwardList; } @Override public boolean contains(@Nullable Object object) { return forwardList.contains(object); } @Override public int indexOf(@Nullable Object object) { int index = forwardList.lastIndexOf(object); return (index >= 0) ? reverseIndex(index) : -1; } @Override public int lastIndexOf(@Nullable Object object) { int index = forwardList.indexOf(object); return (index >= 0) ? reverseIndex(index) : -1; } @Override public ImmutableList subList(int fromIndex, int toIndex) { checkPositionIndexes(fromIndex, toIndex, size()); return forwardList.subList( reversePosition(toIndex), reversePosition(fromIndex)).reverse(); } @Override public E get(int index) { checkElementIndex(index, size()); return forwardList.get(reverseIndex(index)); } @Override public int size() { return forwardList.size(); } @Override boolean isPartialView() { return forwardList.isPartialView(); } } @Override public boolean equals(@Nullable Object obj) { return Lists.equalsImpl(this, obj); } @Override public int hashCode() { int hashCode = 1; int n = size(); for (int i = 0; i < n; i++) { hashCode = 31 * hashCode + get(i).hashCode(); hashCode = ~~hashCode; // needed to deal with GWT integer overflow } return hashCode; } /* * Serializes ImmutableLists as their logical contents. This ensures that * implementation types do not leak into the serialized representation. */ static class SerializedForm implements Serializable { final Object[] elements; SerializedForm(Object[] elements) { this.elements = elements; } Object readResolve() { return copyOf(elements); } private static final long serialVersionUID = 0; } private void readObject(ObjectInputStream stream) throws InvalidObjectException { throw new InvalidObjectException("Use SerializedForm"); } @Override Object writeReplace() { return new SerializedForm(toArray()); } /** * Returns a new builder. The generated builder is equivalent to the builder * created by the {@link Builder} constructor. */ public static Builder builder() { return new Builder(); } /** * A builder for creating immutable list instances, especially {@code public * static final} lists ("constant lists"). Example:

   {@code
   *
   *   public static final ImmutableList GOOGLE_COLORS
   *       = new ImmutableList.Builder()
   *           .addAll(WEBSAFE_COLORS)
   *           .add(new Color(0, 191, 255))
   *           .build();}
* *

Builder instances can be reused; it is safe to call {@link #build} multiple * times to build multiple lists in series. Each new list contains all the * elements of the ones created before it. * * @since 2.0 (imported from Google Collections Library) */ public static final class Builder extends ImmutableCollection.ArrayBasedBuilder { /** * Creates a new builder. The returned builder is equivalent to the builder * generated by {@link ImmutableList#builder}. */ public Builder() { this(DEFAULT_INITIAL_CAPACITY); } // TODO(user): consider exposing this Builder(int capacity) { super(capacity); } /** * Adds {@code element} to the {@code ImmutableList}. * * @param element the element to add * @return this {@code Builder} object * @throws NullPointerException if {@code element} is null */ @Override public Builder add(E element) { super.add(element); return this; } /** * Adds each element of {@code elements} to the {@code ImmutableList}. * * @param elements the {@code Iterable} to add to the {@code ImmutableList} * @return this {@code Builder} object * @throws NullPointerException if {@code elements} is null or contains a * null element */ @Override public Builder addAll(Iterable elements) { super.addAll(elements); return this; } /** * Adds each element of {@code elements} to the {@code ImmutableList}. * * @param elements the {@code Iterable} to add to the {@code ImmutableList} * @return this {@code Builder} object * @throws NullPointerException if {@code elements} is null or contains a * null element */ @Override public Builder add(E... elements) { super.add(elements); return this; } /** * Adds each element of {@code elements} to the {@code ImmutableList}. * * @param elements the {@code Iterable} to add to the {@code ImmutableList} * @return this {@code Builder} object * @throws NullPointerException if {@code elements} is null or contains a * null element */ @Override public Builder addAll(Iterator elements) { super.addAll(elements); return this; } /** * Returns a newly-created {@code ImmutableList} based on the contents of * the {@code Builder}. */ @Override public ImmutableList build() { return asImmutableList(contents, size); } } }