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