From a1c87639762b2b9172c1a775fbd3cfaa66536ab0 Mon Sep 17 00:00:00 2001 From: Gilles Dubochet Date: Fri, 2 Mar 2007 18:49:36 +0000 Subject: Better documentation for Enumeration class. --- src/library/scala/Enumeration.scala | 107 +++++++++++++++++++++++------------- 1 file changed, 69 insertions(+), 38 deletions(-) (limited to 'src/library') diff --git a/src/library/scala/Enumeration.scala b/src/library/scala/Enumeration.scala index bdd2846272..d7d02e210b 100644 --- a/src/library/scala/Enumeration.scala +++ b/src/library/scala/Enumeration.scala @@ -14,36 +14,42 @@ package scala import scala.collection.mutable.{Map, HashMap} -/** - *

The class Enumeration provides the same functionality as the - * enum construct found in C-like languages like C++ or Java. - * Here is an example:

- * 
- * object Main extends Application {
- *
- *   object WeekDays extends Enumeration  {
- *     val Mon, Tue, Wed, Thu, Fri, Sat, Sun = Value
- *   }
- *
- *   def isWorkingDay(d: WeekDays.Value) =
- *     ! (d == WeekDays.Sat || d == WeekDays.Sun)
- *
- *   WeekDays filter (isWorkingDay) foreach { d => Console.println(d) }
- * }
- *
- * - * @param initial the initial integer value associated with the first element - * @param names the sequence of element names of the enumeration - * - * @author Matthias Zenger - * @version 1.0, 10/02/04 - */ +/**

Defines a finite set of values specific to the enumeration. Typically + * these values enumerate all possible forms something can take and provide a + * lightweight alternative to case classes.

+ *

Each call to a Value method adds a new unique value to the + * enumeration. To be accessible, these values are usually defined as + * val members of the evaluation

+ *

All values in an enumeration share a common, unique type defined as the + * Value type member of the enumeration (Value + * selected on the stable identifier path of the enumeration instance).

+ *

Example use

+ * 
+  * object Main extends Application {
+  *
+  *   object WeekDays extends Enumeration  {
+  *     val Mon, Tue, Wed, Thu, Fri, Sat, Sun = Value
+  *   }
+  *
+  *   def isWorkingDay(d: WeekDays.Value) =
+  *     ! (d == WeekDays.Sat || d == WeekDays.Sun)
+  *
+  *   WeekDays filter (isWorkingDay) foreach { d => Console.println(d) }
+  * }
+ * + * @param initial The initial value from which to count the integers that + * identifies values at run-time. + * @param names The sequence of names to give to this enumeration's values. + * + * @author Matthias Zenger + * @version 1.0, 10/02/04 */ abstract class Enumeration(initial: Int, names: String*) { def this() = this(0, null) def this(names: String*) = this(0, names: _*) + /** The name of this enumeration. */ def name = { val cname = this.getClass().getName() if (cname.endsWith("$")) @@ -54,15 +60,11 @@ abstract class Enumeration(initial: Int, names: String*) { cname } - /** - * A mapping between the enumeration value id and the enumeration - * object. - */ - private var values: Map[Int, Value] = new HashMap + /** The mapping from the integer used to identifying values to the actual + * values. */ + private val values: Map[Int, Value] = new HashMap - /** - * A cache listing all values of this enumeration. - */ + /** The cache listing all values of this enumeration. */ private var vcache: List[Value] = null private def updateCache: List[Value] = @@ -72,53 +74,81 @@ abstract class Enumeration(initial: Int, names: String*) { } else vcache; + /** The integer to use to identify the next created value. */ protected var nextId = initial + /** The string to use to name the next created value. */ protected var nextName = names.elements + /** The highest integer amongst those used to identify values in this + * enumeration. */ private var topId = initial + /** The highest integer amongst those used to identify values in this + * enumeration. */ final def maxId = topId - /** - * Returns the enumeration value for the given id. - */ + /** The value in this enumeration identified by integer x. */ final def apply(x: Int): Value = values(x) - /** - * Returns all values of this enumeration. - */ + /** A new iterator over all values of this enumeration. */ final def elements: Iterator[Value] = updateCache.elements + /** Apply a function f to all values of this enumeration. */ def foreach(f: Value => Unit): Unit = elements foreach f + /** Apply a predicate p to all values of this enumeration and return + * true, iff the predicate yields true for all values. */ def forall(p: Value => Boolean): Boolean = elements forall p + /** Apply a predicate p to all values of this enumeration and return + * true, iff there is at least one value for which p yields true. */ def exists(p: Value => Boolean): Boolean = elements exists p + /** Returns an iterator resulting from applying the given function f to each + * value of this enumeration. */ def map[b](f: Value => b): Iterator[b] = elements map f + /** Applies the given function f to each value of this enumeration, then + * concatenates the results. */ def flatMap[b](f: Value => Iterator[b]): Iterator[b] = elements flatMap f + /** Returns all values of this enumeration that satisfy the predicate p. + * The order of values is preserved. */ def filter(p: Value => Boolean): Iterator[Value] = elements filter p override def toString(): String = updateCache.mkString("{", ", ", "}") + /** Creates a fresh value, part of this enumeration. */ protected final def Value: Value = new Val(nextId, if (nextName.hasNext) nextName.next else null) + /** Creates a fresh value, part of this enumeration, identified by the integer + * i. + * @param i An integer that identifies this value at run-time. It must be + * unique amongst all values of the enumeration. */ protected final def Value(i: Int): Value = new Val(i, if (nextName.hasNext) nextName.next else null) + /** Creates a fresh value, part of this enumeration, called name. + * @param name A human-readable name for that value. */ protected final def Value(name: String): Value = new Val(nextId, name) + /** Creates a fresh value, part of this enumeration, called name + * and identified by the integer i. + * @param i An integer that identifies this value at run-time. It must be + * unique amongst all values of the enumeration. + * @param name A human-readable name for that value. */ protected final def Value(i: Int, name: String): Value = new Val(i, name) + /** The type of the enumerated values. */ abstract class Value extends Ordered[Value] { def id: Int override def compare(that: Value): Int = this.id - that.id } + /** A class implementing the Value type. This class can be overriden to + * change the enumeration's naming and integer identification behaviour. */ protected class Val(i: Int, name: String) extends Value { def this(i: Int) = this(i, if (nextName.hasNext) nextName.next else i.toString()) @@ -135,4 +165,5 @@ abstract class Enumeration(initial: Int, names: String*) { if (name eq null) Enumeration.this.name + "(" + i + ")" else name } + } -- cgit v1.2.3