EnumSet.java revision 3909
0N/A * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A * or visit www.oracle.com if you need additional information or have any 0N/A * A specialized {@link Set} implementation for use with enum types. All of 0N/A * the elements in an enum set must come from a single enum type that is 0N/A * specified, explicitly or implicitly, when the set is created. Enum sets 0N/A * are represented internally as bit vectors. This representation is 0N/A * extremely compact and efficient. The space and time performance of this 0N/A * class should be good enough to allow its use as a high-quality, typesafe 0N/A * alternative to traditional <tt>int</tt>-based "bit flags." Even bulk 0N/A * operations (such as <tt>containsAll</tt> and <tt>retainAll</tt>) should 0N/A * run very quickly if their argument is also an enum set. 0N/A * <p>The iterator returned by the <tt>iterator</tt> method traverses the 0N/A * elements in their <i>natural order</i> (the order in which the enum 0N/A * constants are declared). The returned iterator is <i>weakly 0N/A * consistent</i>: it will never throw {@link ConcurrentModificationException} 0N/A * and it may or may not show the effects of any modifications to the set that 0N/A * occur while the iteration is in progress. 0N/A * <p>Null elements are not permitted. Attempts to insert a null element 0N/A * will throw {@link NullPointerException}. Attempts to test for the 0N/A * presence of a null element or to remove one will, however, function 0N/A * <P>Like most collection implementations, <tt>EnumSet</tt> is not 0N/A * synchronized. If multiple threads access an enum set concurrently, and at 0N/A * least one of the threads modifies the set, it should be synchronized * externally. This is typically accomplished by synchronizing on some * object that naturally encapsulates the enum set. If no such object exists, * the set should be "wrapped" using the {@link Collections#synchronizedSet} * method. This is best done at creation time, to prevent accidental * Set<MyEnum> s = Collections.synchronizedSet(EnumSet.noneOf(MyEnum.class)); * <p>Implementation note: All basic operations execute in constant time. * They are likely (though not guaranteed) to be much faster than their * {@link HashSet} counterparts. Even bulk operations execute in * constant time if their argument is also an enum set. * <p>This class is a member of the * Java Collections Framework</a>. * The class of all the elements of this set. * All of the values comprising T. (Cached for performance.) * Creates an empty enum set with the specified element type. * @param elementType the class object of the element type for this enum * @throws NullPointerException if <tt>elementType</tt> is null * Creates an enum set containing all of the elements in the specified * @param elementType the class object of the element type for this enum * @throws NullPointerException if <tt>elementType</tt> is null * Adds all of the elements from the appropriate enum type to this enum * set, which is empty prior to the call. * Creates an enum set with the same element type as the specified enum * set, initially containing the same elements (if any). * @param s the enum set from which to initialize this enum set * @throws NullPointerException if <tt>s</tt> is null * Creates an enum set initialized from the specified collection. If * the specified collection is an <tt>EnumSet</tt> instance, this static * factory method behaves identically to {@link #copyOf(EnumSet)}. * Otherwise, the specified collection must contain at least one element * (in order to determine the new enum set's element type). * @param c the collection from which to initialize this enum set * @throws IllegalArgumentException if <tt>c</tt> is not an * <tt>EnumSet</tt> instance and contains no elements * @throws NullPointerException if <tt>c</tt> is null * Creates an enum set with the same element type as the specified enum * set, initially containing all the elements of this type that are * <i>not</i> contained in the specified set. * @param s the enum set from whose complement to initialize this enum set * @throws NullPointerException if <tt>s</tt> is null * Creates an enum set initially containing the specified element. * Overloadings of this method exist to initialize an enum set with * one through five elements. A sixth overloading is provided that * uses the varargs feature. This overloading may be used to create * an enum set initially containing an arbitrary number of elements, but * is likely to run slower than the overloadings that do not use varargs. * @param e the element that this set is to contain initially * @throws NullPointerException if <tt>e</tt> is null * @return an enum set initially containing the specified element * Creates an enum set initially containing the specified elements. * Overloadings of this method exist to initialize an enum set with * one through five elements. A sixth overloading is provided that * uses the varargs feature. This overloading may be used to create * an enum set initially containing an arbitrary number of elements, but * is likely to run slower than the overloadings that do not use varargs. * @param e1 an element that this set is to contain initially * @param e2 another element that this set is to contain initially * @throws NullPointerException if any parameters are null * @return an enum set initially containing the specified elements * Creates an enum set initially containing the specified elements. * Overloadings of this method exist to initialize an enum set with * one through five elements. A sixth overloading is provided that * uses the varargs feature. This overloading may be used to create * an enum set initially containing an arbitrary number of elements, but * is likely to run slower than the overloadings that do not use varargs. * @param e1 an element that this set is to contain initially * @param e2 another element that this set is to contain initially * @param e3 another element that this set is to contain initially * @throws NullPointerException if any parameters are null * @return an enum set initially containing the specified elements * Creates an enum set initially containing the specified elements. * Overloadings of this method exist to initialize an enum set with * one through five elements. A sixth overloading is provided that * uses the varargs feature. This overloading may be used to create * an enum set initially containing an arbitrary number of elements, but * is likely to run slower than the overloadings that do not use varargs. * @param e1 an element that this set is to contain initially * @param e2 another element that this set is to contain initially * @param e3 another element that this set is to contain initially * @param e4 another element that this set is to contain initially * @throws NullPointerException if any parameters are null * @return an enum set initially containing the specified elements * Creates an enum set initially containing the specified elements. * Overloadings of this method exist to initialize an enum set with * one through five elements. A sixth overloading is provided that * uses the varargs feature. This overloading may be used to create * an enum set initially containing an arbitrary number of elements, but * is likely to run slower than the overloadings that do not use varargs. * @param e1 an element that this set is to contain initially * @param e2 another element that this set is to contain initially * @param e3 another element that this set is to contain initially * @param e4 another element that this set is to contain initially * @param e5 another element that this set is to contain initially * @throws NullPointerException if any parameters are null * @return an enum set initially containing the specified elements * Creates an enum set initially containing the specified elements. * This factory, whose parameter list uses the varargs feature, may * be used to create an enum set initially containing an arbitrary * number of elements, but it is likely to run slower than the overloadings * that do not use varargs. * @param first an element that the set is to contain initially * @param rest the remaining elements the set is to contain initially * @throws NullPointerException if any of the specified elements are null, * or if <tt>rest</tt> is null * @return an enum set initially containing the specified elements * Creates an enum set initially containing all of the elements in the * range defined by the two specified endpoints. The returned set will * contain the endpoints themselves, which may be identical but must not * @param from the first element in the range * @param to the last element in the range * @throws NullPointerException if {@code from} or {@code to} are null * @throws IllegalArgumentException if {@code from.compareTo(to) > 0} * @return an enum set initially containing all of the elements in the * range defined by the two specified endpoints * Adds the specified range to this enum set, which is empty prior * Returns a copy of this set. * @return a copy of this set * Complements the contents of this enum set. * Throws an exception if e is not of the correct type for this enum set. * Returns all of the values comprising E. * The result is uncloned, cached, and shared by all callers. * This class is used to serialize all EnumSet instances, regardless of * implementation type. It captures their "logical contents" and they * are reconstructed using public static factories. This is necessary * to ensure that the existence of a particular implementation type is * an implementation detail. * The element type of this enum set. * The elements contained in this enum set. // readObject method for the serialization proxy pattern // See Effective Java, Second Ed., Item 78.