From 8ac36547ea50936a87963dfc2ac8d2da6771c76f Mon Sep 17 00:00:00 2001 From: Matthias Zenger Date: Sun, 31 Aug 2003 22:57:22 +0000 Subject: [PATCH] Added more comments, removed StructuralEquality... Added more comments, removed StructuralEquality trait. --- sources/scala/BufferedIterator.scala | 18 +- sources/scala/Iterable.scala | 22 +- sources/scala/List.scala | 414 +++++++++--------- sources/scala/PartialFunction.scala | 24 +- sources/scala/Predef.scala | 46 +- sources/scala/Seq.scala | 38 +- sources/scala/collection/Map.scala | 122 +++--- sources/scala/collection/Set.scala | 54 ++- .../scala/collection/immutable/Queue.scala | 118 +++-- .../scala/collection/immutable/Stack.scala | 103 ++--- sources/scala/collection/mutable/Buffer.scala | 77 ++-- sources/scala/collection/mutable/Map.scala | 7 + sources/scala/collection/mutable/Queue.scala | 73 ++- sources/scala/collection/mutable/Set.scala | 7 + sources/scala/collection/mutable/Stack.scala | 86 ++-- 15 files changed, 589 insertions(+), 620 deletions(-) diff --git a/sources/scala/BufferedIterator.scala b/sources/scala/BufferedIterator.scala index a27f4cc34fb5..e17093e1d249 100644 --- a/sources/scala/BufferedIterator.scala +++ b/sources/scala/BufferedIterator.scala @@ -4,27 +4,23 @@ ** __\ \/ /__/ __ |/ /__/ __ | ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** +** $Id$ \* */ -// $Id$ - package scala; -/** - * Buffered iterators are iterators which allow to inspect the next - * element without discarding it. +/** Buffered iterators are iterators which allow to inspect the next + * element without discarding it. * - * @author Martin Odersky - * @version 1.0, 16/07/2003 + * @author Martin Odersky + * @version 1.0, 16/07/2003 */ trait BufferedIterator[+A] extends Iterator[A] { - /** - * Checks what the next available element is. + /** Checks what the next available element is. * - * @return the current element + * @return the current element */ def head: A; - } diff --git a/sources/scala/Iterable.scala b/sources/scala/Iterable.scala index bd13c40dfea9..5a71864148d1 100644 --- a/sources/scala/Iterable.scala +++ b/sources/scala/Iterable.scala @@ -4,29 +4,25 @@ ** __\ \/ /__/ __ |/ /__/ __ | ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** +** $Id$ \* */ -// $Id$ - package scala; -/** - * Collection classes supporting this trait provide a method - * elements which returns an iterator over all the - * elements contained in the collection. +/** Collection classes supporting this trait provide a method + * elements which returns an iterator over all the + * elements contained in the collection. * - * @author Matthias Zenger - * @version 1.0, 16/07/2003 + * @author Matthias Zenger + * @version 1.0, 16/07/2003 */ trait Iterable[+A] { - /** - * Creates a new iterator over all elements contained in this - * object. + /** Creates a new iterator over all elements contained in this + * object. * - * @return the new iterator + * @return the new iterator */ def elements: Iterator[A]; - } diff --git a/sources/scala/List.scala b/sources/scala/List.scala index 85800af09fed..c131315a0487 100644 --- a/sources/scala/List.scala +++ b/sources/scala/List.scala @@ -10,39 +10,39 @@ package scala; -/** - * This object provides methods for creating specialized lists, and for - * transforming special kinds of lists (e.g. lists of lists). +/** This object provides methods for creating specialized lists, and for + * transforming special kinds of lists (e.g. lists of lists). * * @author Martin Odersky and others * @version 1.0, 15/07/2003 */ object List { - /** - * Create a sorted list of all integers in a range. - * @return the sorted list of all integers in range [from;end). + + /** Create a sorted list of all integers in a range. + * + * @return the sorted list of all integers in range [from;end). */ def range(from: Int, end: Int): List[Int] = if (from >= end) Nil else from :: range(from + 1, end); - /** - * Create a list containing several copies of an element. - * @param n the length of the resulting list - * @param elem the element composing the resulting list - * @return a list composed of n elements all equal to elem + /** Create a list containing several copies of an element. + * + * @param n the length of the resulting list + * @param elem the element composing the resulting list + * @return a list composed of n elements all equal to elem */ def make[a](n: int, elem: a): List[a] = if (n == 0) Nil else elem :: make(n - 1, elem); - /** - * Create a list by applying a function to successive integers. - * @param n the length of the resulting list - * @param maker the procedure which, given an integer n, returns the - * nth element of the resulting list, where n is in [0;n). - * @return the list obtained by applying the maker function to successive - * integers from 0 to n (exclusive). + /** Create a list by applying a function to successive integers. + * + * @param n the length of the resulting list + * @param maker the procedure which, given an integer n, returns the + * nth element of the resulting list, where n is in [0;n). + * @return the list obtained by applying the maker function to successive + * integers from 0 to n (exclusive). */ def tabulate[a](n: int, maker: int => a): List[a] = { def loop(i: int): List[a] = @@ -51,21 +51,18 @@ object List { loop(0) } - /** - * Concatenate all the elements of a given list of lists. - * @param l the list of lists that are to be concatenated - * @return the concatenation of all the lists + /** Concatenate all the elements of a given list of lists. + * @param l the list of lists that are to be concatenated + * @return the concatenation of all the lists */ def flatten[a](l: List[List[a]]): List[a] = l match { case Nil => Nil case head :: tail => head ::: flatten(tail) } - /** - * Transform a list of pair into a pair of lists. - * @param l the list of pairs to unzip - * @return a pair of lists: the first list in the pair contains the - * list + /** Transform a list of pair into a pair of lists. + * @param l the list of pairs to unzip + * @return a pair of lists: the first list in the pair contains the list */ def unzip[a,b](l: List[Pair[a,b]]): Pair[List[a], List[b]] = l match { case Nil => Pair(Nil, Nil) @@ -84,7 +81,7 @@ object List { * @author Martin Odersky and others * @version 1.0, 16/07/2003 */ -trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { +trait List[+a] extends Seq[a] { /** Tests if this list is empty. * @return true, iff the list contains no element. @@ -92,46 +89,46 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { def isEmpty: Boolean; /** Returns this first element of the list. - * @return the first element of this list. - * @throws java.lang.RuntimeException if the list is empty. - */ + * @return the first element of this list. + * @throws java.lang.RuntimeException if the list is empty. + */ def head: a; /** Returns this list without its first element. - * @return this list without its first element. - * @throws java.lang.RuntimeException if the list is empty. - */ + * @return this list without its first element. + * @throws java.lang.RuntimeException if the list is empty. + */ def tail: List[a]; /** Add an element x at the beginning of this list. - *

- * Ex:
- * 1 :: [2, 3] = [2, 3].::(1) = [1, 2, 3]. - * @param x the element to append. - * @return the list with x appended at the beginning. - */ + *

+ * Ex:
+ * 1 :: [2, 3] = [2, 3].::(1) = [1, 2, 3]. + * @param x the element to append. + * @return the list with x appended at the beginning. + */ def ::[b >: a](x: b): List[b] = new scala.::(x, this); /** Returns a list resulting from the concatenation of the given - * list prefix and this list. - *

- * Ex:
- * [1, 2] ::: [3, 4] = [3, 4].:::([1, 2]) = [1, 2, 3, 4]. - * @param prefix the list to concatenate at the beginning of this list. - * @return the concatenation of the two lists. - */ + * list prefix and this list. + *

+ * Ex:
+ * [1, 2] ::: [3, 4] = [3, 4].:::([1, 2]) = [1, 2, 3, 4]. + * @param prefix the list to concatenate at the beginning of this list. + * @return the concatenation of the two lists. + */ def :::[b >: a](prefix: List[b]): List[b] = prefix match { case Nil => this case head :: tail => head :: (tail ::: this); }; /** Reverse the given prefix and append the current list to that. - * This function is equivalent to an application of reverse - * on the prefix followed by a call to :::, but more - * efficient (and tail recursive). - * @param prefix the prefix to reverse and then prepend - * @return the concatenation of the reversed prefix and the current list. + * This function is equivalent to an application of reverse + * on the prefix followed by a call to :::, but more + * efficient (and tail recursive). + * @param prefix the prefix to reverse and then prepend + * @return the concatenation of the reversed prefix and the current list. */ def reverse_:::[b >: a](prefix: List[b]): List[b] = prefix match { case Nil => this @@ -139,8 +136,8 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { }; /** Returns the number of elements in the list. - * @return the number of elements in the list. - */ + * @return the number of elements in the list. + */ def length: Int = match { case Nil => 0 case _ :: xs => xs.length + 1 @@ -160,8 +157,8 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { }; /** Returns the list without its last element. - * @return the list without its last element. - * @throws java.lang.RuntimeException if the list is empty. + * @return the list without its last element. + * @throws java.lang.RuntimeException if the list is empty. */ def init: List[a] = match { case Nil => error("Nil.init") @@ -170,9 +167,9 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { }; /** Returns the last element of this list. - * @return the last element of the list. - * @throws java.lang.RuntimeException if the list is empty. - */ + * @return the last element of the list. + * @throws java.lang.RuntimeException if the list is empty. + */ def last: a = match { case Nil => error("Nil.last") case last :: Nil => last @@ -180,27 +177,27 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { } /** Returns the n first elements of this list. - * @param n the number of elements to take. - * @return the n first elements of this list. - * @throws java.lang.RuntimeException if the list is too short. - */ + * @param n the number of elements to take. + * @return the n first elements of this list. + * @throws java.lang.RuntimeException if the list is too short. + */ def take(n: Int): List[a] = if (n == 0) Nil else head :: (tail take (n-1)); /** Returns the list without its n first elements. - * @param n the number of elements to drop. - * @return the list without its n first elements. - * @throws java.lang.RuntimeException if the list is too short. - */ + * @param n the number of elements to drop. + * @return the list without its n first elements. + * @throws java.lang.RuntimeException if the list is too short. + */ def drop(n: Int): List[a] = if (n == 0) this else (tail drop (n-1)); /** Return the rightmost n elements from this list. - * @param n the number of elements to take - * @return the suffix of length n of the list - * @throws java.lang.RuntimeException if the list is too short. + * @param n the number of elements to take + * @return the suffix of length n of the list + * @throws java.lang.RuntimeException if the list is too short. */ def takeRight(n: Int): List[a] = { def loop(lead: List[a], lag: List[a]): List[a] = lead match { @@ -211,9 +208,9 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { }; /** Return the list wihout its rightmost n elements. - * @param n the number of elements to take - * @return the suffix of length n of the list - * @throws java.lang.RuntimeException if the list is too short. + * @param n the number of elements to take + * @return the suffix of length n of the list + * @throws java.lang.RuntimeException if the list is too short. */ def dropRight(n: Int): List[a] = { def loop(lead: List[a], lag: List[a]): List[a] = lead match { @@ -224,10 +221,10 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { } /** Split the list at a given point and return the two parts thus - * created. - * @param n the position at which to split - * @return a pair of lists composed of the first n - * elements, and the other elements. + * created. + * @param n the position at which to split + * @return a pair of lists composed of the first n + * elements, and the other elements. */ def splitAt(n: Int): Pair[List[a], List[a]] = if (n == 0) Pair(Nil, this) @@ -237,30 +234,30 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { }; /** Returns the longest prefix of this list whose elements satisfy - * the predicate p. - * @param p the test predicate. - * @return the longest prefix of this list whose elements satisfy - * the predicate p. - */ + * the predicate p. + * @param p the test predicate. + * @return the longest prefix of this list whose elements satisfy + * the predicate p. + */ def takeWhile(p: a => Boolean): List[a] = if (isEmpty || !p(head)) Nil else head :: (tail takeWhile p); /** Returns the longest suffix of this list whose first element does not satisfy - * the predicate p. - * @param p the test predicate. - * @return the longest suffix of the list whose first element does not satisfy - * the predicate p. - */ + * the predicate p. + * @param p the test predicate. + * @return the longest suffix of the list whose first element does not satisfy + * the predicate p. + */ def dropWhile(p: a => Boolean): List[a] = if (isEmpty || !p(head)) this else tail dropWhile p; /** Return the longest prefix of the list whose elements all satisfy - * the given predicate, and the rest of the list. - * @param p the test predicate - * @return a pair consisting of the longest prefix of the list whose - * elements all satisfy p, and the rest of the list. + * the given predicate, and the rest of the list. + * @param p the test predicate + * @return a pair consisting of the longest prefix of the list whose + * elements all satisfy p, and the rest of the list. */ def span(p: a => Boolean): Pair[List[a], List[a]] = match { case Nil => Pair(Nil, Nil) @@ -277,29 +274,28 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { def break(p: a => Boolean): Pair[List[a], List[a]] = span { x => !p(x) }; /** Returns the n-th element of this list. The first element - * (head of the list) is at position 0. - * @param n index of the element to return - * @return the element at position n in this list. - * @throws java.lang.RuntimeException if the list is too short. + * (head of the list) is at position 0. + * @param n index of the element to return + * @return the element at position n in this list. + * @throws java.lang.RuntimeException if the list is too short. */ def apply(n: Int): a = drop(n).head; /** Returns the list resulting from applying the given function f to each - * element of this list. - * @param f function to apply to each element. - * @return [f(a0), ..., f(an)] if this list is [a0, ..., an]. - */ + * element of this list. + * @param f function to apply to each element. + * @return [f(a0), ..., f(an)] if this list is [a0, ..., an]. + */ def map[b](f: a => b): List[b] = match { case Nil => Nil case head :: tail => f(head) :: (tail map f) }; - /** - * Apply a function to all the elements of the list, and return the - * reversed list of results. This is equivalent to a call to map - * followed by a call to reverse, but more efficient. - * @param f the function to apply to each elements. - * @return the reversed list of results. + /** Apply a function to all the elements of the list, and return the + * reversed list of results. This is equivalent to a call to map + * followed by a call to reverse, but more efficient. + * @param f the function to apply to each elements. + * @return the reversed list of results. */ def reverseMap[b](f: a => b): List[b] = { def loop(l: List[a], res: List[b]): List[b] = l match { @@ -310,18 +306,18 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { }; /** Apply the given function f to each element of this list - * (while respecting the order of the elements). - * @param f the treatment to apply to each element. - */ + * (while respecting the order of the elements). + * @param f the treatment to apply to each element. + */ def foreach(f: a => Unit): Unit = match { case Nil => () case head :: tail => f(head); tail foreach f }; /** Returns all the elements of this list that satisfy the - * predicate p. The order of the elements is preserved. - * @param p the redicate used to filter the list. - * @return the elements of this list satisfying p. + * predicate p. The order of the elements is preserved. + * @param p the redicate used to filter the list. + * @return the elements of this list satisfying p. */ def filter(p: a => Boolean): List[a] = match { case Nil => this @@ -329,12 +325,11 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { if (p(head)) head :: (tail filter p) else tail filter p }; - /** - * Remove all elements of the list which satisfy the predicate - * p. This is like filter with the - * predicate inversed. - * @param p the predicate to use to test elements - * @return the list without all elements which satisfy p + /** Remove all elements of the list which satisfy the predicate + * p. This is like filter with the + * predicate inversed. + * @param p the predicate to use to test elements + * @return the list without all elements which satisfy p */ def remove(p: a => Boolean): List[a] = match { case Nil => this @@ -342,14 +337,13 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { if (p(head)) tail remove p else head :: (tail remove p) }; - /** - * Partition the list in two sub-lists according to a predicate. - * @param p the predicate on which to partition - * @return a pair of lists: the list of all elements which satisfy - * p and the list of all elements which do not. The - * relative order of the elements in the sub-lists is the same as in - * the original list. */ - + /** Partition the list in two sub-lists according to a predicate. + * @param p the predicate on which to partition + * @return a pair of lists: the list of all elements which satisfy + * p and the list of all elements which do not. The + * relative order of the elements in the sub-lists is the same as in + * the original list. + */ def partition(p: a => Boolean): Pair[List[a], List[a]] = match { case Nil => Pair(Nil, Nil) case head :: tail => @@ -358,10 +352,9 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { else Pair(taily, head :: tailn) }; - /** - * Count the number of elements in the list which satisfy a predicate. - * @param p the predicate for which to count - * @return the number of elements satisfying p. + /** Count the number of elements in the list which satisfy a predicate. + * @param p the predicate for which to count + * @return the number of elements satisfying p. */ def count(p: a => Boolean): Int = match { case Nil => 0 @@ -369,28 +362,27 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { }; /** Tests if the predicate p is satisfied by all elements in this - * list. - * @param p the test predicate. - * @return True iff all elements of this list satisfy the predicate p. - */ + * list. + * @param p the test predicate. + * @return True iff all elements of this list satisfy the predicate p. + */ def forall(p: a => Boolean): Boolean = isEmpty || (p(head) && (tail forall p)); /** Tests the existence in this list of an element that satisfies the predicate - * p. - * @param p the test predicate. - * @return True iff there exists an element in this list that satisfies - * the predicate p. - */ + * p. + * @param p the test predicate. + * @return true iff there exists an element in this list that satisfies + * the predicate p. + */ def exists(p: a => Boolean): Boolean = !isEmpty && (p(head) || (tail exists p)); - /** - * Find and return the first element of the list satisfying a - * predicate, if any. - * @param p the predicate - * @return the first element in the list satisfying p, - * or None if none exists. + /** Find and return the first element of the list satisfying a + * predicate, if any. + * @param p the predicate + * @return the first element in the list satisfying p, + * or None if none exists. */ def find(p: a => Boolean): Option[a] = match { case Nil => None @@ -398,13 +390,13 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { }; /** Combines the elements of this list together using the binary - * operator op, from left to right, and starting with - * the value z. Similar to fold but with - * a different order of the arguments, allowing to use nice constructions like - * (z foldLeft l) { ... }. - * @return op(... (op(op(z,a0),a1) ...), an) if the list - * is [a0, a1, ..., an]. - */ + * operator op, from left to right, and starting with + * the value z. Similar to fold but with + * a different order of the arguments, allowing to use nice constructions like + * (z foldLeft l) { ... }. + * @return op(... (op(op(z,a0),a1) ...), an) if the list + * is [a0, a1, ..., an]. + */ def foldLeft[b](z: b)(f: (b, a) => b): b = match { case Nil => z case x :: xs => xs.foldLeft[b](f(z, x))(f) @@ -429,24 +421,23 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { case x :: xs => f(x, xs reduceRight f) }; - /** - * Applies the given function f to each element of - * this list, then concatenates the results. - * @param f the function to apply on each element. - * @return f(a0) ::: ... ::: f(an) if this list is - * [a0, ..., an]. - */ + /** Applies the given function f to each element of + * this list, then concatenates the results. + * @param f the function to apply on each element. + * @return f(a0) ::: ... ::: f(an) if this list is + * [a0, ..., an]. + */ def flatMap[b](f: a => List[b]): List[b] = match { case Nil => Nil case head :: tail => f(head) ::: (tail flatMap f) }; /** Reverses the elements of this list. - *

- * Ex:
- * [1, 2, 3] reverse = [3, 2, 1]. - * @return the elements of this list in reverse order. - */ + *

+ * Ex:
+ * [1, 2, 3] reverse = [3, 2, 1]. + * @return the elements of this list in reverse order. + */ def reverse: List[a] = foldLeft(Nil : List[a])((xs, x) => x :: xs); @@ -459,31 +450,31 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { */ /** Fills the given array xs with the elements of - * this list starting at position start. Does not - * work with empty lists. - * @param xs the array to fill. - * @param start starting index. - * @return the given array xs filled with this list. - * @throws error if the list is empty. - */ + * this list starting at position start. Does not + * work with empty lists. + * @param xs the array to fill. + * @param start starting index. + * @return the given array xs filled with this list. + * @throws error if the list is empty. + */ def copyToArray[b >: a](xs: Array[b], start: Int): int = match { case Nil => start case y :: ys => xs(start) = y; ys.copyToArray(xs, start + 1) } /** Returns a string representation of this list. The resulting string - * begins with the string start and is finished by the string - * end. Inside, the string representations of elements (w.r.t. - * the method toString()) are separated by the string - * sep. - *

- * Ex:
- * List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)" - * @param start starting string. - * @param sep separator string. - * @param end ending string. - * @return a string representation of this list. - */ + * begins with the string start and is finished by the string + * end. Inside, the string representations of elements (w.r.t. + * the method toString()) are separated by the string + * sep. + *

+ * Ex:
+ * List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)" + * @param start starting string. + * @param sep separator string. + * @param end ending string. + * @return a string representation of this list. + */ def mkString(start: String, sep: String, end: String): String = match { case Nil => start + end case last :: Nil => start + last + end @@ -493,31 +484,30 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { override def toString() = mkString("List(", ",", ")"); /** Return a list formed from this list and the specified list - * that by associating each element of the former with - * the element at the same position in the latter. - * @param that must have the same length as the self list. - * @return [(a0,b0), ..., (an,bn)] when - * [a0, ..., an] zip [b0, ..., bn] is invoked. - * @throws java.lang.RuntimeException if lists have different lengths. - */ + * that by associating each element of the former with + * the element at the same position in the latter. + * @param that must have the same length as the self list. + * @return [(a0,b0), ..., (an,bn)] when + * [a0, ..., an] zip [b0, ..., bn] is invoked. + * @throws java.lang.RuntimeException if lists have different lengths. + */ def zip[b](that: List[b]): List[Pair[a,b]] = if (this.isEmpty || that.isEmpty) Nil else Pair(this.head, that.head) :: this.tail.zip(that.tail); - /** Tests if the given value elem is a member of - * this list. - * @param elem element whose membership has to be tested. - * @return True iff there is an element of this list which is - * equal (w.r.t. ==) to elem. - */ + /** Tests if the given value elem is a member of this list. + * @param elem element whose membership has to be tested. + * @return True iff there is an element of this list which is + * equal (w.r.t. ==) to elem. + */ def contains(elem: Any): boolean = exists { x => x == elem }; /** Computes the union of this list and the given list - * that. - * @param that the list of elements to add to the list. - * @return a list without doubles containing the elements of this - * list and those of the given list that. - */ + * that. + * @param that the list of elements to add to the list. + * @return a list without doubles containing the elements of this + * list and those of the given list that. + */ def union[b >: a](that: List[b]): List[b] = match { case Nil => that case head :: tail => @@ -526,10 +516,10 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { } /** Computes the difference between this list and the given list - * that. - * @param that the list of elements to remove from this list. - * @return this list without the elements of the given list that. - */ + * that. + * @param that the list of elements to remove from this list. + * @return this list without the elements of the given list that. + */ def diff[b >: a](that: List[b]): List[b] = match { case Nil => Nil case head :: tail => @@ -538,17 +528,17 @@ trait List[+a] extends Seq[a]/* with StructuralEquality[List[a]]*/ { } /** Computes the intersection between this list and the given list - * that. - * @param that the list to intersect. - * @return the list of elements contained both in this list and - * in the given list that. - */ + * that. + * @param that the list to intersect. + * @return the list of elements contained both in this list and + * in the given list that. + */ def intersect[b >: a](that: List[b]): List[b] = filter(x => that contains x); /** Removes redundant elements from the list. Uses the method == - * to decide if two elements are identical. - * @return the list without doubles. - */ + * to decide if two elements are identical. + * @return the list without doubles. + */ def removeDuplicates: List[a] = match { case Nil => this case head :: tail => diff --git a/sources/scala/PartialFunction.scala b/sources/scala/PartialFunction.scala index 2d72625b76a7..69adb778b6da 100644 --- a/sources/scala/PartialFunction.scala +++ b/sources/scala/PartialFunction.scala @@ -4,30 +4,26 @@ ** __\ \/ /__/ __ |/ /__/ __ | ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** +** $Id$ \* */ -// $Id$ - package scala; -/** - * A partial function of type PartialFunction[A, B] is a - * unary function where the domain does not include all values of type - * A. The function isDefinedAt allows to - * test dynamically, if a value is in the domain of the function. +/** A partial function of type PartialFunction[A, B] is a + * unary function where the domain does not include all values of type + * A. The function isDefinedAt allows to + * test dynamically, if a value is in the domain of the function. * - * @author Martin Odersky - * @version 1.0, 16/07/2003 + * @author Martin Odersky + * @version 1.0, 16/07/2003 */ trait PartialFunction[-A, +B] with Function1[A, B] { - /** - * Checks if a value is contained in the functions domain. + /** Checks if a value is contained in the functions domain. * - * @param x the value to test - * @return true, iff x is in the domain of this function. + * @param x the value to test + * @return true, iff x is in the domain of this function. */ def isDefinedAt(x: A): Boolean; - } diff --git a/sources/scala/Predef.scala b/sources/scala/Predef.scala index ad2cb8e7a596..c85835fdf243 100644 --- a/sources/scala/Predef.scala +++ b/sources/scala/Predef.scala @@ -1,5 +1,19 @@ +/* __ *\ +** ________ ___ / / ___ Scala API ** +** / __/ __// _ | / / / _ | (c) 2002-2003, LAMP/EPFL ** +** __\ \/ /__/ __ |/ /__/ __ | ** +** /____/\___/_/ |_/____/_/ | | ** +** |/ ** +** $Id$ +\* */ + package scala; + +/** The Predef object provides definitions that are + * accessible in all Scala compilation units without explicit + * qualification. + */ object Predef { type byte = scala.Byte; @@ -15,33 +29,29 @@ object Predef { def List[A](x: A*): List[A] = x.asInstanceOf[List[A]]; val List = scala.List; -/* - def Set[A](es: A*): scala.Set[A] = { - val set = new HashSet[A]; - set.addSet(es); - set; - } - - def Map[A, B](mappings: Pair[A, B]*): MutableMap[A, B] = { - val map = new HashMap[A, B]; - map.putMap(mappings); - map; - } -*/ - - def error(x: String): All = throw new java.lang.RuntimeException(x); + def error(message: String): All = throw new Error(message); def exit: scala.Unit = System.exit(0); - def id[a](x: a): a = x; - - def synchronized[A](obj: AnyRef)(def body: A) = + def synchronized[A](obj: AnyRef)(def body: A): A = scala.runtime.NativeMonitor.synchronised(obj, body); + def assert(assertion: Boolean): Unit = { + if (!assertion) + throw new Error("assertion failed"); + } + def assert(assertion: Boolean, message: String): Unit = { + if (!assertion) + throw new Error(message); + } + type Pair[p, q] = Tuple2[p, q]; def Pair[a, b](x: a, y: b) = Tuple2(x, y); type Triple[a, b, c] = Tuple3[a, b, c]; def Triple[a, b, c](x: a, y: b, z: c) = Tuple3(x, y, z); + def id[a](x: a): a = x; + def fst[a](x: a, y: Any): a = x; + def scd[a](x: Any, y: a): a = y; } diff --git a/sources/scala/Seq.scala b/sources/scala/Seq.scala index 29a63c2f729c..fac644ab4a80 100644 --- a/sources/scala/Seq.scala +++ b/sources/scala/Seq.scala @@ -4,54 +4,48 @@ ** __\ \/ /__/ __ |/ /__/ __ | ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** +** $Id$ \* */ -// $Id$ - package scala; -/** - * Class Seq[A] represents finite sequences of elements - * of type A. +/** Class Seq[A] represents finite sequences of elements + * of type A. * - * @author Martin Odersky - * @version 1.0, 16/07/2003 + * @author Martin Odersky + * @version 1.0, 16/07/2003 */ trait Seq[+A] with PartialFunction[Int, A] with Iterable[A] { - /** - * Returns the length of the sequence. + /** Returns the length of the sequence. * - * @return the sequence length. + * @return the sequence length. */ def length: Int; - /** - * Is this partial function defined for the index x? + /** Is this partial function defined for the index x? * - * @return true, iff x is a legal sequence index. + * @return true, iff x is a legal sequence index. */ def isDefinedAt(x: Int): Boolean = (x >= 0) && (x < length); - /** - * Customizes the toString method. + /** Customizes the toString method. * - * @return a string representation of this sequence. + * @return a string representation of this sequence. */ override def toString() = { def toString1(it: Iterator[A]):String = { - if (it.hasNext) { - ",".concat(it.next.toString()) + if (it.hasNext) { + ",".concat(it.next.toString()) .concat(toString1(it)) - } else + } else ")" } val it = elements; if (it.hasNext) - "Seq(" + it.next.toString() + toString1(it) + "Seq(" + it.next.toString() + toString1(it) else - "Seq()" + "Seq()" } - } diff --git a/sources/scala/collection/Map.scala b/sources/scala/collection/Map.scala index 82ae25a317ca..1bb586ef0750 100644 --- a/sources/scala/collection/Map.scala +++ b/sources/scala/collection/Map.scala @@ -11,82 +11,73 @@ package scala.collection; -/** - * This trait defines the interface of collections that unambiguously map - * keys to values (i.e. a key is mapped to at least one value). - * Trait Map may only be used for - * accessing elements from map implementations. Two different extensions - * of trait Map in the package scala.collections.mutable - * and scala.collections.immutable provide functionality for - * adding new key/value mappings to a map. The trait in the first package is - * implemented by maps that are modified destructively, whereas the trait in - * the second package is used by functional map implementations that rely on - * immutable data structures. +/** This trait defines the interface of collections that unambiguously map + * keys to values (i.e. a key is mapped to at least one value). + * Trait Map may only be used for + * accessing elements from map implementations. Two different extensions + * of trait Map in the package scala.collections.mutable + * and scala.collections.immutable provide functionality for + * adding new key/value mappings to a map. The trait in the first package is + * implemented by maps that are modified destructively, whereas the trait in + * the second package is used by functional map implementations that rely on + * immutable data structures. * - * @author Matthias Zenger - * @version 1.0, 08/07/2003 + * @author Matthias Zenger + * @version 1.0, 08/07/2003 */ trait Map[A, +B] with PartialFunction[A, B] - with Iterable[Pair[A, B]] - with StructuralEquality[Map[A, B]]{ + with Iterable[Pair[A, B]] { - /** - * Compute the number of key-to-value mappings. + /** Compute the number of key-to-value mappings. * - * @return the number of mappings + * @return the number of mappings */ def size: Int; - /** - * Check if this map maps key to a value and return the - * value if it exists. + /** Check if this map maps key to a value and return the + * value if it exists. * - * @param key the key of the mapping of interest - * @return the value of the mapping, if it exists + * @param key the key of the mapping of interest + * @return the value of the mapping, if it exists */ def get(key: A): Option[B]; - /** - * Is this an empty map? + /** Is this an empty map? * * @return true, iff the map is empty. */ def isEmpty: Boolean = (size == 0); - /** - * Retrieve the value which is associated with the given key. This - * method throws an exception if there is no mapping from the given - * key to a value. + /** Retrieve the value which is associated with the given key. This + * method throws an exception if there is no mapping from the given + * key to a value. * - * @param key the key - * @return the value associated with the given key. + * @param key the key + * @return the value associated with the given key. */ def apply(key: A): B = get(key) match { case None => error("key not found") case Some(value) => value } - /** - * Is the given key mapped to a value by this map? + /** Is the given key mapped to a value by this map? * - * @param key the key - * @return true, iff there is a mapping for key in this map + * @param key the key + * @return true, iff there is a mapping for key in this map */ def contains(key: A): Boolean = get(key) match { case None => false case Some(_) => true } - /** - * Does this map contain a mapping from the given key to a value? + /** Does this map contain a mapping from the given key to a value? * - * @param key the key - * @return true, iff there is a mapping for key in this map + * @param key the key + * @return true, iff there is a mapping for key in this map */ def isDefinedAt(key: A) = contains(key); - /** - * Creates an iterator for all keys. + /** Creates an iterator for all keys. * * @return an iterator over all keys. */ @@ -96,10 +87,9 @@ trait Map[A, +B] with PartialFunction[A, B] def next = iter.next._1; } - /** - * Creates an iterator for a contained values. + /** Creates an iterator for a contained values. * - * @return an iterator over all values. + * @return an iterator over all values. */ def values: Iterator[B] = new Iterator[B] { val iter = Map.this.elements; @@ -107,11 +97,10 @@ trait Map[A, +B] with PartialFunction[A, B] def next = iter.next._2; } - /** - * Executes the given function for all (key, value) pairs - * contained in this map. + /** Executes the given function for all (key, value) pairs + * contained in this map. * - * @param f the function to execute. + * @param f the function to execute. */ def foreach(f: (A, B) => Unit) = { val iter = elements; @@ -121,8 +110,7 @@ trait Map[A, +B] with PartialFunction[A, B] } } - /** - * Applies the given predicate to all (key, value) mappings + /** Applies the given predicate to all (key, value) mappings * contained in this map and returns true if this predicate * yields true for all mappings. * @@ -133,23 +121,21 @@ trait Map[A, +B] with PartialFunction[A, B] case Pair(key, value) => p(key, value) } - /** - * Applies the given predicate to all (key, value) mappings - * contained in this map and returns true if there is at least - * one mapping for which this predicate yields true. + /** Applies the given predicate to all (key, value) mappings + * contained in this map and returns true if there is at least + * one mapping for which this predicate yields true. * - * @param p the predicate - * @return true, iff there is at least one mapping for which - * p yields true. + * @param p the predicate + * @return true, iff there is at least one mapping for which + * p yields true. */ def exists(p: (A, B) => Boolean): Boolean = elements.exists { case Pair(key, value) => p(key, value) } - /** - * Creates a list of all (key, value) mappings. + /** Creates a list of all (key, value) mappings. * - * @return the list of all mappings + * @return the list of all mappings */ def toList: List[Pair[A, B]] = { var res: List[Pair[A, B]] = Nil; @@ -157,14 +143,13 @@ trait Map[A, +B] with PartialFunction[A, B] res; } - /** - * Compares two maps structurally; i.e. checks if all mappings - * contained in this map are also contained in the other map, - * and vice versa. + /** Compares two maps structurally; i.e. checks if all mappings + * contained in this map are also contained in the other map, + * and vice versa. * - * @return true, iff both maps contain exactly the same mappings. + * @return true, iff both maps contain exactly the same mappings. */ - override def ===[C >: Map[A, B]](that: C): Boolean = + override def equals(that: Any): Boolean = that.isInstanceOf[Map[A, B]] && { val other = that.asInstanceOf[Map[A, B]]; this.size == other.size && @@ -175,10 +160,9 @@ trait Map[A, +B] with PartialFunction[A, B] } }}; - /** - * Creates a string representation for this map. + /** Creates a string representation for this map. * - * @return a string showing all mappings + * @return a string showing all mappings */ override def toString() = if (size == 0) diff --git a/sources/scala/collection/Set.scala b/sources/scala/collection/Set.scala index cee20b3241e9..cb8a47c466f7 100644 --- a/sources/scala/collection/Set.scala +++ b/sources/scala/collection/Set.scala @@ -23,35 +23,83 @@ package scala.collection; * @author Matthias Zenger * @version 1.0, 08/07/2003 */ -trait Set[A] with Iterable[A] - with StructuralEquality[Set[A]] { +trait Set[A] with Iterable[A] { + /** Returns the number of elements in this set. + * + * @return number of set elements. + */ def size: Int; + /** Checks if this set contains element elem. + * + * @param elem the element to check for membership. + * @return true, iff elem is contained in this set. + */ def contains(elem: A): Boolean; + /** Checks if this set is empty. + * + * @return true, iff there is no element in the set. + */ def isEmpty: Boolean = (size == 0); + /** Checks if this set is a subset of set that. + * + * @param that another set. + * @return true, iff the other set is a superset of this set. + */ def subsetOf(that: Set[A]): Boolean = forall(that.contains); + /** Execute the statement f for every element in this set. + * + * @param f a function that is applied to every element in this set. + */ def foreach(f: A => Unit): Unit = elements.foreach(f); + /** Checks if a given predicate is true for all elements in this set. + * + * @param p the predicate + * @returns true, iff the predicate yields true for all elements. + */ def forall(p: A => Boolean): Boolean = elements.forall(p); + /** Checks if a given predicate is true for at least one element + * in this set. + * + * @param p the predicate + * @returns true, iff the predicate yields true for at least one element. + */ def exists(p: A => Boolean): Boolean = elements.exists(p); + /** Transform this set into a list of all elements. + * + * @return a list which enumerates all elements of this set. + */ def toList: List[A] = { var res: List[A] = Nil; elements.foreach { elem => res = elem :: res; } res; } - override def ===[B >: Set[A]](that: B): Boolean = + /** Compares this set with another object and returns true, iff the + * other object is also a set which contains the same elements as + * this set. + * + * @param that the other object + * @return true, iff this set and the other set contain the same + * elements. + */ + override def equals(that: Any): Boolean = that.isInstanceOf[Set[A]] && { val other = that.asInstanceOf[Set[A]]; this.size == other.size && this.elements.forall(other.contains) }; + /** Returns a string representation of this set. + * + * @return a string showing all elements of this set. + */ override def toString(): String = if (size == 0) "{}" diff --git a/sources/scala/collection/immutable/Queue.scala b/sources/scala/collection/immutable/Queue.scala index d8158da5e267..f8199b1c52ab 100644 --- a/sources/scala/collection/immutable/Queue.scala +++ b/sources/scala/collection/immutable/Queue.scala @@ -4,25 +4,23 @@ ** __\ \/ /__/ __ |/ /__/ __ | ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** +** $Id$ \* */ -// $Id$ - package scala.collection.immutable; -/** - * Queue objects implement data structures that allow to - * insert and retrieve elements in a first-in-first-out (FIFO) manner. - * - * @author Erik Stenman - * @version 1.0, 08/07/2003 - */ + object Queue { val Empty:Queue[All] = new Queue(); } -class Queue[+A](elem: A*) extends Seq[A] - with StructuralEquality[Queue[A]] { +/** Queue objects implement data structures that allow to + * insert and retrieve elements in a first-in-first-out (FIFO) manner. + * + * @author Erik Stenman + * @version 1.0, 08/07/2003 + */ +class Queue[+A](elem: A*) extends Seq[A] { protected val in:List[A] = Nil; protected val out:List[A] = itToList(elem.elements); @@ -38,52 +36,45 @@ class Queue[+A](elem: A*) extends Seq[A] }; } - /** - * Returns the n-th element of this queue. - * The first element is at position 0. + /** Returns the n-th element of this queue. + * The first element is at position 0. * - * @param n index of the element to return - * @return the element at position n in this list. - * @throws java.lang.RuntimeException if the list is too short. + * @param n index of the element to return + * @return the element at position n in this list. + * @throws java.lang.RuntimeException if the list is too short. */ def apply(n: Int): A = if (n < out.length) out.apply(n) else in.reverse.apply(n - out.length); - /** - * Returns the elements in the list as an iterator + /** Returns the elements in the list as an iterator */ def elements: Iterator[A] = (out:::(in.reverse)).elements; - /** - * Checks if the queue is empty. + /** Checks if the queue is empty. * - * @return true, iff there is no element in the queue. + * @return true, iff there is no element in the queue. */ def isEmpty: Boolean = (in.isEmpty && out.isEmpty); - /** - * Returns the length of the queue. + /** Returns the length of the queue. */ def length = in.length + out.length; - /** - * Creates a new queue with element added at the end - * of the old queue. + /** Creates a new queue with element added at the end + * of the old queue. * - * @param elem the element to insert + * @param elem the element to insert */ - def +[B >: A](elem: B) = mkQueue(elem::in,out); - /** - * Returns a new queue with all all elements provided by - * an Iterable object added at the end of - * the queue. - * The elements are prepended in the order they - * are given out by the iterator. + /** Returns a new queue with all all elements provided by + * an Iterable object added at the end of + * the queue. + * The elements are prepended in the order they + * are given out by the iterator. * - * @param iter an iterable object + * @param iter an iterable object */ def +[B >: A](iter: Iterable[B]) = { var q:List[B] = in; @@ -91,18 +82,16 @@ class Queue[+A](elem: A*) extends Seq[A] mkQueue(q, out); } - /** - * Returns a new queue with all elements added. + /** Returns a new queue with all elements added. * - * @param elems the elements to add. + * @param elems the elements to add. */ def enqueue [B >: A](elems: B*) = (this + elems); - /** - * Returns a tuple with the first element in the queue, - * and a new queue with this element removed. + /** Returns a tuple with the first element in the queue, + * and a new queue with this element removed. * - * @return the first element of the queue. + * @return the first element of the queue. */ def dequeue:Pair[A,Queue[A]] = { var newOut:List[A] = Nil; @@ -120,11 +109,10 @@ class Queue[+A](elem: A*) extends Seq[A] Pair(newOut.head, mkQueue(newIn, newOut.tail)); } - /** - * Returns the first element in the queue, or throws an error if there - * is no element contained in the queue. + /** Returns the first element in the queue, or throws an error if there + * is no element contained in the queue. * - * @return the first element. + * @return the first element. */ def front: A = if (out.isEmpty) { @@ -132,34 +120,31 @@ class Queue[+A](elem: A*) extends Seq[A] } else out.head; - /** - * Returns a string representation of this queue. The resulting string - * begins with the string start and is finished by the string - * end. Inside, the string representations of elements (w.r.t. - * the method toString()) are separated by the string - * sep. - *

- * Ex:
- * Queue(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)" + /** Returns a string representation of this queue. The resulting string + * begins with the string start and is finished by the string + * end. Inside, the string representations of elements (w.r.t. + * the method toString()) are separated by the string + * sep. + *

+ * Ex:
+ * Queue(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)" * - * @param start starting string. - * @param sep separator string. - * @param end ending string. - * @return a string representation of this list. + * @param start starting string. + * @param sep separator string. + * @param end ending string. + * @return a string representation of this list. */ def mkString(start: String, sep: String, end: String): String = (out ::: (in.reverse)).mkString(start,sep,end); - /** - * Returns a string representation of this queue. + /** Returns a string representation of this queue. */ override def toString() = (out ::: (in.reverse)).mkString("Queue(", ",", ")"); - /** - * Compares two queues for equality by comparing - * each element in the queues. + /** Compares two queues for equality by comparing + * each element in the queues. * - * @return true, iff the two queues are structurally equal. + * @return true, iff the two queues are structurally equal. */ override def equals(o: Any): Boolean = o match { case q: Queue[Any] => @@ -183,5 +168,4 @@ class Queue[+A](elem: A*) extends Seq[A] case _ => false; /* o is not a queue: not equal to this. */ } - } diff --git a/sources/scala/collection/immutable/Stack.scala b/sources/scala/collection/immutable/Stack.scala index 5ba966a6b967..e648eace409e 100644 --- a/sources/scala/collection/immutable/Stack.scala +++ b/sources/scala/collection/immutable/Stack.scala @@ -4,10 +4,9 @@ ** __\ \/ /__/ __ |/ /__/ __ | ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** +** $Id$ \* */ -// $Id$ - package scala.collection.immutable; @@ -15,46 +14,41 @@ object Stack { def Empty[A] = new Stack[A]; } -/** - * This class implements immutable stacks using a list-based data - * structure. Instances of Stack represent - * empty stacks; they can be either created by calling the constructor - * directly, or by applying the function Stack.Empty. +/** This class implements immutable stacks using a list-based data + * structure. Instances of Stack represent + * empty stacks; they can be either created by calling the constructor + * directly, or by applying the function Stack.Empty. * - * @author Matthias Zenger - * @version 1.0, 10/07/2003 + * @author Matthias Zenger + * @version 1.0, 10/07/2003 */ -class Stack[+A] with Seq[A] with StructuralEquality[Stack[A]] { +class Stack[+A] with Seq[A] { - /** - * Checks if this stack is empty. + /** Checks if this stack is empty. * - * @return true, iff there is no element on the stack. + * @return true, iff there is no element on the stack. */ def isEmpty: Boolean = true; - /** - * Returns the size of this stack. + /** Returns the size of this stack. * - * @return the stack size. + * @return the stack size. */ def length: Int = 0; - /** - * Push an element on the stack. + /** Push an element on the stack. * - * @param elem the element to push on the stack. - * @return the stack with the new element on top. + * @param elem the element to push on the stack. + * @return the stack with the new element on top. */ def +[B >: A](elem: B): Stack[B] = new Node(elem); - /** - * Push all elements provided by the given iterable object onto - * the stack. The last element returned by the iterable object - * will be on top of the new stack. + /** Push all elements provided by the given iterable object onto + * the stack. The last element returned by the iterable object + * will be on top of the new stack. * - * @param elems the iterable object. - * @return the stack with the new elements on top. + * @param elems the iterable object. + * @return the stack with the new elements on top. */ def +[B >: A](elems: Iterable[B]): Stack[B] = { var res: Stack[B] = this; @@ -62,60 +56,53 @@ class Stack[+A] with Seq[A] with StructuralEquality[Stack[A]] { res; } - /** - * Push a sequence of elements onto the stack. The last element - * of the sequence will be on top of the new stack. + /** Push a sequence of elements onto the stack. The last element + * of the sequence will be on top of the new stack. * - * @param elems the element sequence. - * @return the stack with the new elements on top. + * @param elems the element sequence. + * @return the stack with the new elements on top. */ def push[B >: A](elems: B*): Stack[B] = this + elems; - /** - * Returns the top element of the stack. An error is signaled if - * there is no element on the stack. + /** Returns the top element of the stack. An error is signaled if + * there is no element on the stack. * - * @return the top element. + * @return the top element. */ def top: A = error("no element on stack"); - /** - * Removes the top element from the stack. + /** Removes the top element from the stack. * - * @return the new stack without the former top element. + * @return the new stack without the former top element. */ def pop: Stack[A] = error("no element on stack"); - /** - * Returns the n-th element of this stack. The top element has index - * 0, elements below are indexed with increasing numbers. + /** Returns the n-th element of this stack. The top element has index + * 0, elements below are indexed with increasing numbers. * - * @param n the index number. - * @return the n-th element on the stack. + * @param n the index number. + * @return the n-th element on the stack. */ def apply(n: Int): A = error("no element on stack"); - /** - * Returns an iterator over all elements on the stack. The iterator - * issues elements in the reversed order they were inserted into the - * stack (LIFO order). + /** Returns an iterator over all elements on the stack. The iterator + * issues elements in the reversed order they were inserted into the + * stack (LIFO order). * - * @return an iterator over all stack elements. + * @return an iterator over all stack elements. */ def elements: Iterator[A] = toList.elements; - /** - * Creates a list of all stack elements in LIFO order. + /** Creates a list of all stack elements in LIFO order. * - * @return the created list. + * @return the created list. */ def toList: List[A] = Nil; - /** - * Compares this stack with the given object. + /** Compares this stack with the given object. * - * @return true, iff the two stacks are equal; i.e. they contain the - * same elements in the same order. + * @return true, iff the two stacks are equal; i.e. they contain the + * same elements in the same order. */ override def equals(obj: Any): Boolean = if (obj.isInstanceOf[Stack[A]]) @@ -123,10 +110,9 @@ class Stack[+A] with Seq[A] with StructuralEquality[Stack[A]] { else false; - /** - * Returns the hash code for this stack. + /** Returns the hash code for this stack. * - * @return the hash code of the stack. + * @return the hash code of the stack. */ override def hashCode(): Int = 0; @@ -143,5 +129,4 @@ class Stack[+A] with Seq[A] with StructuralEquality[Stack[A]] { override def toList: List[B] = elem :: Stack.this.toList; override def hashCode(): Int = elem.hashCode() + Stack.this.hashCode(); } - } diff --git a/sources/scala/collection/mutable/Buffer.scala b/sources/scala/collection/mutable/Buffer.scala index 8a6ee778d832..e04a32234aaa 100644 --- a/sources/scala/collection/mutable/Buffer.scala +++ b/sources/scala/collection/mutable/Buffer.scala @@ -4,57 +4,52 @@ ** __\ \/ /__/ __ |/ /__/ __ | ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** +** $Id$ \* */ -// $Id$ - package scala.collection.mutable; -/** - * Buffers are used to create sequences of elements incrementally by - * appending or prepending new elements. It is also possible to - * access and modify elements in a random access fashion via the - * index of the element in the sequence. +/** Buffers are used to create sequences of elements incrementally by + * appending or prepending new elements. It is also possible to + * access and modify elements in a random access fashion via the + * index of the element in the sequence. * - * @author Matthias Zenger - * @version 1.0, 08/07/2003 + * @author Matthias Zenger + * @version 1.0, 08/07/2003 */ -class Buffer[A] with MutableList[A] with StructuralEquality[Buffer[A]] { +class Buffer[A] with MutableList[A] { - /** - * .. + /** Prepend an element to this list. * - * @param elem + * @param elem the element to prepend. */ def prepend(elem: A) = prependElem(elem); - /** - * .. + /** Appends a sequence of elements to this buffer. * - * @param elems + * @param elems the elements to append. */ def append(elems: A*) = (this += elems); - /** - * .. + /** Append a single element to this buffer. * - * @param elem + * @param elem the element to append. */ def +=(elem: A) = appendElem(elem); - /** - * .. + /** Appends a number of elements provided by an iterable object + * via its elements method. * - * @param iter + * @param iter the iterable object. */ def +=(iter: Iterable[A]) = iter.elements.foreach(e => appendElem(e)); - /** - * .. + /** Replace element at index n with the new element + * newelem. * - * @param n - * @param newelem + * @param n the index of the element to replace. + * @param newelem the new element. */ def update(n: Int, newelem: A): Unit = { var elem = first; @@ -68,11 +63,12 @@ class Buffer[A] with MutableList[A] with StructuralEquality[Buffer[A]] { elem.elem = newelem; } - /** - * .. + /** Inserts a new element at the index n. Opposed to method + * update, this method will not replace an element with a + * one. Instead, it will insert a new element at index n. * - * @param n - * @param newelem + * @param n the index where a new element will be inserted. + * @param newelem the new element to insert. */ def insert(n: Int, newelem: A): Unit = { if (n == 0) @@ -93,10 +89,9 @@ class Buffer[A] with MutableList[A] with StructuralEquality[Buffer[A]] { } } - /** - * .. + /** Removes the element on a given index position. * - * @param n + * @param n the index which refers to the element to delete. */ def remove(n: Int): A = { val old = apply(n); @@ -123,21 +118,25 @@ class Buffer[A] with MutableList[A] with StructuralEquality[Buffer[A]] { old; } - /** - * Clears the buffer contents + /** Clears the buffer contents. */ def clear: Unit = reset; - /** - * Checks if two buffers are structurally identical. + /** Checks if two buffers are structurally identical. * - * @return true, iff both buffers contain the same sequence of elements. + * @return true, iff both buffers contain the same sequence of elements. */ - override def ===[B >: Buffer[A]](that: B) = + override def equals(that: Any): Boolean = that.isInstanceOf[Buffer[A]] && { val other = that.asInstanceOf[Buffer[A]]; elements.zip(other.elements).forall { case Pair(thiselem, thatelem) => thiselem == thatelem; }}; + /** The hashCode method always yields an error, since it is not + * safe to use buffers as keys in hash tables. + * + * @return never. + */ + override def hashCode(): Int = error("unsuitable as hash key"); } diff --git a/sources/scala/collection/mutable/Map.scala b/sources/scala/collection/mutable/Map.scala index 5d0b7059df43..e63107bcfb79 100644 --- a/sources/scala/collection/mutable/Map.scala +++ b/sources/scala/collection/mutable/Map.scala @@ -87,6 +87,13 @@ trait Map[A, B] with scala.collection.Map[A, B] { case Pair(key, value) => if (p(key, value)) -=(key); } + /** The hashCode method always yields an error, since it is not + * safe to use mutable maps as keys in hash tables. + * + * @return never. + */ + override def hashCode(): Int = error("unsuitable as hash key"); + /** Returns a string representation of this map which shows * all the mappings. */ diff --git a/sources/scala/collection/mutable/Queue.scala b/sources/scala/collection/mutable/Queue.scala index 55e36b15121b..cc41b4019727 100644 --- a/sources/scala/collection/mutable/Queue.scala +++ b/sources/scala/collection/mutable/Queue.scala @@ -4,57 +4,50 @@ ** __\ \/ /__/ __ |/ /__/ __ | ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** +** $Id$ \* */ -// $Id$ - package scala.collection.mutable; -/** - * Queue objects implement data structures that allow to - * insert and retrieve elements in a first-in-first-out (FIFO) manner. +/** Queue objects implement data structures that allow to + * insert and retrieve elements in a first-in-first-out (FIFO) manner. * - * @author Matthias Zenger - * @version 1.0, 08/07/2003 + * @author Matthias Zenger + * @version 1.0, 08/07/2003 */ class Queue[A] with MutableList[A] { - /** - * Checks if the queue is empty. + /** Checks if the queue is empty. * - * @return true, iff there is no element in the queue. + * @return true, iff there is no element in the queue. */ def isEmpty: Boolean = (first == null); - /** - * Inserts a single element at the end of the queue. + /** Inserts a single element at the end of the queue. * - * @param elem the element to insert + * @param elem the element to insert */ def +=(elem: A) = appendElem(elem); - /** - * Adds all elements provided by an Iterable object - * at the end of the queue. The elements are prepended in the order they - * are given out by the iterator. + /** Adds all elements provided by an Iterable object + * at the end of the queue. The elements are prepended in the order they + * are given out by the iterator. * - * @param iter an iterable object + * @param iter an iterable object */ def +=(iter: Iterable[A]) = iter.elements.foreach(e => appendElem(e)); - /** - * Adds all elements to the queue. + /** Adds all elements to the queue. * - * @param elems the elements to add. + * @param elems the elements to add. */ def enqueue(elems: A*): Unit = (this += elems); - /** - * Returns the first element in the queue, and removes this element - * from the queue. + /** Returns the first element in the queue, and removes this element + * from the queue. * - * @return the first element of the queue. + * @return the first element of the queue. */ def dequeue: A = { if (first == null) @@ -66,24 +59,21 @@ class Queue[A] with MutableList[A] { } } - /** - * Returns the first element in the queue, or throws an error if there - * is no element contained in the queue. + /** Returns the first element in the queue, or throws an error if there + * is no element contained in the queue. * - * @return the first element. + * @return the first element. */ def front: A = first.elem; - /** - * Removes all elements from the queue. After this operation is completed, - * the queue will be empty. + /** Removes all elements from the queue. After this operation is completed, + * the queue will be empty. */ def clear: Unit = reset; - /** - * Checks if two queues are structurally identical. + /** Checks if two queues are structurally identical. * - * @return true, iff both queues contain the same sequence of elements. + * @return true, iff both queues contain the same sequence of elements. */ override def equals(that: Any): Boolean = that.isInstanceOf[Queue[A]] && @@ -92,19 +82,16 @@ class Queue[A] with MutableList[A] { case Pair(thiselem, thatelem) => thiselem == thatelem; }}; - /** - * The hashCode method always yields an error, since it is not - * safe to use mutable queues as keys in hash tables. + /** The hashCode method always yields an error, since it is not + * safe to use mutable queues as keys in hash tables. * - * @return never. + * @return never. */ override def hashCode(): Int = error("unsuitable as hash key"); - /** - * Returns a textual representation of a queue as a string. + /** Returns a textual representation of a queue as a string. * - * @return the string representation of this queue. + * @return the string representation of this queue. */ override def toString() = toList.mkString("Queue(", ", ", ")"); - } diff --git a/sources/scala/collection/mutable/Set.scala b/sources/scala/collection/mutable/Set.scala index 11691a8bb739..d23452a3f9d1 100644 --- a/sources/scala/collection/mutable/Set.scala +++ b/sources/scala/collection/mutable/Set.scala @@ -69,4 +69,11 @@ trait Set[A] with scala.collection.Set[A] { * the set will be empty. */ def clear: Unit; + + /** The hashCode method always yields an error, since it is not + * safe to use mutable stacks as keys in hash tables. + * + * @return never. + */ + override def hashCode(): Int = error("unsuitable as hash key"); } diff --git a/sources/scala/collection/mutable/Stack.scala b/sources/scala/collection/mutable/Stack.scala index 8c04763a9908..18bec0143381 100644 --- a/sources/scala/collection/mutable/Stack.scala +++ b/sources/scala/collection/mutable/Stack.scala @@ -4,64 +4,56 @@ ** __\ \/ /__/ __ |/ /__/ __ | ** ** /____/\___/_/ |_/____/_/ | | ** ** |/ ** +** $Id$ \* */ -// $Id$ - package scala.collection.mutable; -/** - * A stack implements a data structure which allows to store and retrieve - * objects in a last-in-first-out (LIFO) fashion. +/** A stack implements a data structure which allows to store and retrieve + * objects in a last-in-first-out (LIFO) fashion. * - * @author Matthias Zenger - * @version 1.0, 08/07/2003 + * @author Matthias Zenger + * @version 1.0, 08/07/2003 */ class Stack[A] with MutableList[A] { - /** - * Checks if the stack is empty. + /** Checks if the stack is empty. * - * @return true, iff there is no element on the stack + * @return true, iff there is no element on the stack */ def isEmpty: Boolean = (first == null); - /** - * Pushes a single element on top of the stack. + /** Pushes a single element on top of the stack. * - * @param elem the element to push onto the stack + * @param elem the element to push onto the stack */ def +=(elem: A): Unit = prependElem(elem); - /** - * Pushes all elements provided by an Iterable object - * on top of the stack. The elements are pushed in the order they - * are given out by the iterator. + /** Pushes all elements provided by an Iterable object + * on top of the stack. The elements are pushed in the order they + * are given out by the iterator. * - * @param iter an iterable object + * @param iter an iterable object */ def +=(iter: Iterable[A]): Unit = iter.elements.foreach(e => prependElem(e)); - /** - * Pushes a sequence of elements on top of the stack. The first element - * is pushed first, etc. + /** Pushes a sequence of elements on top of the stack. The first element + * is pushed first, etc. * - * @param elems a sequence of elements + * @param elems a sequence of elements */ def push(elems: A*): Unit = (this += elems); - /** - * Returns the top element of the stack. This method will not remove - * the element from the stack. An error is signaled if there is no - * element on the stack. + /** Returns the top element of the stack. This method will not remove + * the element from the stack. An error is signaled if there is no + * element on the stack. * - * @return the top element + * @return the top element */ def top: A = if (first == null) error("stack empty"); else first.elem; - /** - * Removes the top element from the stack. + /** Removes the top element from the stack. */ def pop: Unit = if (first != null) { first = first.next; } @@ -71,28 +63,25 @@ class Stack[A] with MutableList[A] { */ def clear: Unit = reset; - /** - * Returns an iterator over all elements on the stack. This iterator - * is stable with respect to state changes in the stack object; i.e. - * such changes will not be reflected in the iterator. The iterator - * issues elements in the order they were inserted into the stack - * (FIFO order). + /** Returns an iterator over all elements on the stack. This iterator + * is stable with respect to state changes in the stack object; i.e. + * such changes will not be reflected in the iterator. The iterator + * issues elements in the order they were inserted into the stack + * (FIFO order). * - * @return an iterator over all stack elements. + * @return an iterator over all stack elements. */ override def elements: Iterator[A] = toList.elements; - /** - * Creates a list of all stack elements in FIFO order. + /** Creates a list of all stack elements in FIFO order. * - * @return the created list. + * @return the created list. */ override def toList: List[A] = super[MutableList].toList.reverse; - /** - * Checks if two stacks are structurally identical. + /** Checks if two stacks are structurally identical. * - * @return true, iff both stacks contain the same sequence of elements. + * @return true, iff both stacks contain the same sequence of elements. */ override def equals(that: Any): Boolean = that.isInstanceOf[Stack[A]] && @@ -101,19 +90,16 @@ class Stack[A] with MutableList[A] { case Pair(thiselem, thatelem) => thiselem == thatelem; }}; - /** - * The hashCode method always yields an error, since it is not - * safe to use mutable stacks as keys in hash tables. + /** The hashCode method always yields an error, since it is not + * safe to use mutable stacks as keys in hash tables. * - * @return never. + * @return never. */ override def hashCode(): Int = error("unsuitable as hash key"); - /** - * Returns a textual representation of a stack as a string. + /** Returns a textual representation of a stack as a string. * - * @return the string representation of this stack. + * @return the string representation of this stack. */ override def toString() = toList.mkString("Stack(", ", ", ")"); - }