java.util.EnumSet Maven / Gradle / Ivy
/*
* Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util;
import org.apidesign.bck2brwsr.core.JavaScriptBody;
/**
* A specialized {@link Set} implementation for use with enum types. All of
* the elements in an enum set must come from a single enum type that is
* specified, explicitly or implicitly, when the set is created. Enum sets
* are represented internally as bit vectors. This representation is
* extremely compact and efficient. The space and time performance of this
* class should be good enough to allow its use as a high-quality, typesafe
* alternative to traditional int-based "bit flags." Even bulk
* operations (such as containsAll and retainAll) should
* run very quickly if their argument is also an enum set.
*
* The iterator returned by the iterator method traverses the
* elements in their natural order (the order in which the enum
* constants are declared). The returned iterator is weakly
* consistent: it will never throw {@link ConcurrentModificationException}
* and it may or may not show the effects of any modifications to the set that
* occur while the iteration is in progress.
*
*
Null elements are not permitted. Attempts to insert a null element
* will throw {@link NullPointerException}. Attempts to test for the
* presence of a null element or to remove one will, however, function
* properly.
*
*
Like most collection implementations, EnumSet is not
* synchronized. If multiple threads access an enum set concurrently, and at
* 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
* unsynchronized access:
*
*
* Set<MyEnum> s = Collections.synchronizedSet(EnumSet.noneOf(MyEnum.class));
*
*
* 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.
*
*
This class is a member of the
*
* Java Collections Framework.
*
* @author Josh Bloch
* @since 1.5
* @see EnumMap
* @serial exclude
*/
public abstract class EnumSet> extends AbstractSet
implements Cloneable, java.io.Serializable
{
/**
* The class of all the elements of this set.
*/
final Class elementType;
/**
* All of the values comprising T. (Cached for performance.)
*/
final Enum[] universe;
private static Enum[] ZERO_LENGTH_ENUM_ARRAY = new Enum[0];
EnumSet(ClasselementType, Enum[] universe) {
this.elementType = elementType;
this.universe = universe;
}
/**
* Creates an empty enum set with the specified element type.
*
* @param elementType the class object of the element type for this enum
* set
* @throws NullPointerException if elementType is null
*/
public static > EnumSet noneOf(Class elementType) {
Enum[] universe = getUniverse(elementType);
if (universe == null)
throw new ClassCastException(elementType + " not an enum");
if (universe.length <= 64)
return new RegularEnumSet<>(elementType, universe);
else
return new JumboEnumSet<>(elementType, universe);
}
/**
* Creates an enum set containing all of the elements in the specified
* element type.
*
* @param elementType the class object of the element type for this enum
* set
* @throws NullPointerException if elementType is null
*/
public static > EnumSet allOf(Class elementType) {
EnumSet result = noneOf(elementType);
result.addAll();
return result;
}
/**
* Adds all of the elements from the appropriate enum type to this enum
* set, which is empty prior to the call.
*/
abstract void addAll();
/**
* 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 s is null
*/
public static > EnumSet copyOf(EnumSet s) {
return s.clone();
}
/**
* Creates an enum set initialized from the specified collection. If
* the specified collection is an EnumSet 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 c is not an
* EnumSet instance and contains no elements
* @throws NullPointerException if c is null
*/
public static > EnumSet copyOf(Collection c) {
if (c instanceof EnumSet) {
return ((EnumSet)c).clone();
} else {
if (c.isEmpty())
throw new IllegalArgumentException("Collection is empty");
Iterator i = c.iterator();
E first = i.next();
EnumSet result = EnumSet.of(first);
while (i.hasNext())
result.add(i.next());
return result;
}
}
/**
* Creates an enum set with the same element type as the specified enum
* set, initially containing all the elements of this type that are
* not contained in the specified set.
*
* @param s the enum set from whose complement to initialize this enum set
* @throws NullPointerException if s is null
*/
public static > EnumSet complementOf(EnumSet s) {
EnumSet result = copyOf(s);
result.complement();
return result;
}
/**
* 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 e is null
* @return an enum set initially containing the specified element
*/
public static > EnumSet of(E e) {
EnumSet result = noneOf(e.getDeclaringClass());
result.add(e);
return result;
}
/**
* 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
*/
public static > EnumSet of(E e1, E e2) {
EnumSet result = noneOf(e1.getDeclaringClass());
result.add(e1);
result.add(e2);
return result;
}
/**
* 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
*/
public static > EnumSet of(E e1, E e2, E e3) {
EnumSet result = noneOf(e1.getDeclaringClass());
result.add(e1);
result.add(e2);
result.add(e3);
return result;
}
/**
* 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
*/
public static > EnumSet of(E e1, E e2, E e3, E e4) {
EnumSet result = noneOf(e1.getDeclaringClass());
result.add(e1);
result.add(e2);
result.add(e3);
result.add(e4);
return result;
}
/**
* 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
*/
public static > EnumSet of(E e1, E e2, E e3, E e4,
E e5)
{
EnumSet result = noneOf(e1.getDeclaringClass());
result.add(e1);
result.add(e2);
result.add(e3);
result.add(e4);
result.add(e5);
return result;
}
/**
* 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 rest is null
* @return an enum set initially containing the specified elements
*/
@SafeVarargs
public static > EnumSet of(E first, E... rest) {
EnumSet result = noneOf(first.getDeclaringClass());
result.add(first);
for (E e : rest)
result.add(e);
return result;
}
/**
* 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
* be out of order.
*
* @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
*/
public static > EnumSet range(E from, E to) {
if (from.compareTo(to) > 0)
throw new IllegalArgumentException(from + " > " + to);
EnumSet result = noneOf(from.getDeclaringClass());
result.addRange(from, to);
return result;
}
/**
* Adds the specified range to this enum set, which is empty prior
* to the call.
*/
abstract void addRange(E from, E to);
/**
* Returns a copy of this set.
*
* @return a copy of this set
*/
public EnumSet clone() {
try {
return (EnumSet) super.clone();
} catch(CloneNotSupportedException e) {
throw new AssertionError(e);
}
}
/**
* Complements the contents of this enum set.
*/
abstract void complement();
/**
* Throws an exception if e is not of the correct type for this enum set.
*/
final void typeCheck(E e) {
Class eClass = e.getClass();
if (eClass != elementType && eClass.getSuperclass() != elementType)
throw new ClassCastException(eClass + " != " + elementType);
}
/**
* Returns all of the values comprising E.
* The result is uncloned, cached, and shared by all callers.
*/
@JavaScriptBody(args = { "enumType" }, body = "return enumType.cnstr.prototype['_$VALUES']();")
private static native > E[] getUniverse(Class elementType);
/**
* 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.
*
* @serial include
*/
private static class SerializationProxy >
implements java.io.Serializable
{
/**
* The element type of this enum set.
*
* @serial
*/
private final Class elementType;
/**
* The elements contained in this enum set.
*
* @serial
*/
private final Enum[] elements;
SerializationProxy(EnumSet set) {
elementType = set.elementType;
elements = set.toArray(ZERO_LENGTH_ENUM_ARRAY);
}
private Object readResolve() {
EnumSet result = EnumSet.noneOf(elementType);
for (Enum e : elements)
result.add((E)e);
return result;
}
private static final long serialVersionUID = 362491234563181265L;
}
Object writeReplace() {
return new SerializationProxy<>(this);
}
// readObject method for the serialization proxy pattern
// See Effective Java, Second Ed., Item 78.
private void readObject(java.io.ObjectInputStream stream)
throws java.io.InvalidObjectException {
throw new java.io.InvalidObjectException("Proxy required");
}
}