diff options
author | Andrew John Hughes <gnu_andrew@member.fsf.org> | 2006-04-17 19:21:06 +0000 |
---|---|---|
committer | Andrew John Hughes <gnu_andrew@member.fsf.org> | 2006-04-17 19:21:06 +0000 |
commit | 0358a9cfde987687168a081db9e76f87b0201023 (patch) | |
tree | f02aed7e3856403b12c00a615256231c53eb7c02 /java | |
parent | aa3c4260fa88d14d90e37bba2a734a4c50f5a575 (diff) | |
download | classpath-0358a9cfde987687168a081db9e76f87b0201023.tar.gz |
2006-04-17 Andrew John Hughes <gnu_andrew@member.fsf.org>
* java/lang/Enum.java: Documented.
Diffstat (limited to 'java')
-rw-r--r-- | java/lang/Enum.java | 104 |
1 files changed, 103 insertions, 1 deletions
diff --git a/java/lang/Enum.java b/java/lang/Enum.java index 61a0a638c..82b20e8e2 100644 --- a/java/lang/Enum.java +++ b/java/lang/Enum.java @@ -41,8 +41,15 @@ import java.io.Serializable; import java.lang.reflect.Field; /** + * This class represents a Java enumeration. All enumerations are + * subclasses of this class. + * + * @author Tom Tromey (tromey@redhat.com) + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) * @since 1.5 */ +/* FIXME[GENERICS]: Should be Enum<T extends Enum<T>> + and Comparable<T> */ public abstract class Enum implements Comparable, Serializable { @@ -52,9 +59,24 @@ public abstract class Enum */ private static final long serialVersionUID = -4300926546619394005L; + /** + * The name of this enum constant. + */ String name; + + /** + * The number of this enum constant. Each constant is given a number + * which matches the order in which it was declared, starting with zero. + */ int ordinal; + /** + * This constructor is used by the compiler to create enumeration constants. + * + * @param name the name of the enumeration constant. + * @param ordinal the number of the enumeration constant, based on the + * declaration order of the constants and starting from zero. + */ protected Enum(String name, int ordinal) { this.name = name; @@ -69,6 +91,7 @@ public abstract class Enum * @exception IllegalArgumentException when there is no value s in * the enum etype. */ + /* FIXME[GENERICS]: Should be <S extends Enum<S>> S valueOf(Class<S>) */ public static Enum valueOf(Class etype, String s) { if (etype == null || s == null) @@ -79,7 +102,8 @@ public abstract class Enum Field f = etype.getDeclaredField(s); if (! f.isEnumConstant()) throw new IllegalArgumentException(s); - return (Enum) f.get(null); + /* FIXME[GENERICS]: Should cast to S */ + return (Enum) f.get(null); } catch (NoSuchFieldException exception) { @@ -91,22 +115,58 @@ public abstract class Enum } } + /** + * Returns true if this enumeration is equivalent to the supplied object, + * <code>o</code>. Only one instance of an enumeration constant exists, + * so the comparison is simply done using <code>==</code>. + * + * @param o the object to compare to this. + * @return true if <code>this == o</code>. + */ public final boolean equals(Object o) { // Enum constants are singular, so we need only compare `=='. return this == o; } + /** + * Returns the hash code of this constant. This is simply the ordinal. + * + * @return the hash code of this enumeration constant. + */ public final int hashCode() { return ordinal; } + /** + * Returns a textual representation of this enumeration constant. + * By default, this is simply the declared name of the constant, but + * specific enumeration types may provide an implementation more suited + * to the data being stored. + * + * @return a textual representation of this constant. + */ public String toString() { return name; } + /** + * Returns an integer which represents the relative ordering of this + * enumeration constant. Enumeration constants are ordered by their + * ordinals, which represents their declaration order. So, comparing + * two identical constants yields zero, while one declared prior to + * this returns a positive integer and one declared after yields a + * negative integer. + * + * @param e the enumeration constant to compare. + * @return a negative integer if <code>e.ordinal < this.ordinal</code>, + * zero if <code>e.ordinal == this.ordinal</code> and a positive + * integer if <code>e.ordinal > this.ordinal</code>. + * @throws ClassCastException if <code>e</code> is not an enumeration + * constant of the same class. + */ public final int compareTo(Enum e) { if (getDeclaringClass() != e.getDeclaringClass()) @@ -114,26 +174,68 @@ public abstract class Enum return ordinal - e.ordinal; } + /** + * Returns an integer which represents the relative ordering of this + * enumeration constant. Enumeration constants are ordered by their + * ordinals, which represents their declaration order. So, comparing + * two identical constants yields zero, while one declared prior to + * this returns a positive integer and one declared after yields a + * negative integer. + * + * @param e the enumeration constant to compare. + * @return a negative integer if <code>e.ordinal < this.ordinal</code>, + * zero if <code>e.ordinal == this.ordinal</code> and a positive + * integer if <code>e.ordinal > this.ordinal</code>. + * @throws ClassCastException if <code>e</code> is not an enumeration + * constant of the same class. + */ + /* FIXME[GENERICS]: Remove this method */ public final int compareTo(Object o) { return compareTo((Enum)o); } + /** + * Cloning of enumeration constants is prevented, to maintain their + * singleton status. + * + * @return the cloned object. + * @throws CloneNotSupportedException as enumeration constants can't be + * cloned. + */ protected final Object clone() throws CloneNotSupportedException { throw new CloneNotSupportedException("can't clone an enum constant"); } + /** + * Returns the name of this enumeration constant. + * + * @return the name of the constant. + */ public final String name() { return name; } + /** + * Returns the number of this enumeration constant, which represents + * the order in which it was originally declared, starting from zero. + * + * @return the number of this constant. + */ public final int ordinal() { return ordinal; } + /** + * Returns the type of this enumeration constant. This is the class + * corresponding to the declaration of the enumeration. + * + * @return the type of this enumeration constant. + */ + /* FIXME[GENERICS]: Should return Class<T> */ public final Class getDeclaringClass() { Class k = getClass(); |