diff options
10 files changed, 153 insertions, 45 deletions
diff --git a/src/library/scala/collection/mutable/DoubleLinkedList.scala b/src/library/scala/collection/mutable/DoubleLinkedList.scala index d76ee7fa72..d8b8278c74 100644 --- a/src/library/scala/collection/mutable/DoubleLinkedList.scala +++ b/src/library/scala/collection/mutable/DoubleLinkedList.scala @@ -14,8 +14,8 @@ package mutable import generic._ -/** This class implements double linked lists where both the head (`elem`) - * and the tail (`next`) are mutable. +/** This class implements double linked lists where both the head (`elem`), + * the tail (`next`) and a reference to the previous node (`prev`) are mutable. * * @author Matthias Zenger * @author Martin Odersky diff --git a/src/library/scala/collection/mutable/LazyBuilder.scala b/src/library/scala/collection/mutable/LazyBuilder.scala index 7714d29f08..91cf8f2ad9 100644 --- a/src/library/scala/collection/mutable/LazyBuilder.scala +++ b/src/library/scala/collection/mutable/LazyBuilder.scala @@ -17,6 +17,9 @@ import immutable.{List, Nil} * be added to this builder with `++=` are not evaluated until `result` is called. * * @since 2.8 + * + * @tparam Elem type of the elements for this builder. + * @tparam To type of the collection this builder builds. */ abstract class LazyBuilder[Elem, +To] extends Builder[Elem, To] { /** The different segments of elements to be added to the builder, represented as iterators */ diff --git a/src/library/scala/collection/mutable/LinearSeq.scala b/src/library/scala/collection/mutable/LinearSeq.scala index 23ad4b8c29..185b8c97a3 100644 --- a/src/library/scala/collection/mutable/LinearSeq.scala +++ b/src/library/scala/collection/mutable/LinearSeq.scala @@ -14,9 +14,12 @@ package mutable import generic._ -/** A subtrait of <code>collection.LinearSeq</code> which represents sequences +/** A subtrait of `collection.LinearSeq` which represents sequences * that can be mutated. * $linearSeqInfo + * + * @define Coll LinearSeq + * @define coll linear sequence */ trait LinearSeq[A] extends Seq[A] with scala.collection.LinearSeq[A] diff --git a/src/library/scala/collection/mutable/LinkedEntry.scala b/src/library/scala/collection/mutable/LinkedEntry.scala index 46db4cdf09..5d591058e8 100644 --- a/src/library/scala/collection/mutable/LinkedEntry.scala +++ b/src/library/scala/collection/mutable/LinkedEntry.scala @@ -12,8 +12,8 @@ package scala.collection package mutable -/** - * @since 2.8 +/** Class for the linked hash map entry, used internally. + * @since 2.8 */ @serializable final class LinkedEntry[A, B](val key: A, var value: B) diff --git a/src/library/scala/collection/mutable/LinkedHashMap.scala b/src/library/scala/collection/mutable/LinkedHashMap.scala index 2636219727..97961ccd9c 100644 --- a/src/library/scala/collection/mutable/LinkedHashMap.scala +++ b/src/library/scala/collection/mutable/LinkedHashMap.scala @@ -14,20 +14,36 @@ package mutable import generic._ -/** This class implements mutable maps using a hashtable. - * The iterator and all traversal methods of this class visit elements in the order they were inserted. - * - * @author Martin Odersky - * @version 2.8 - * @since 2.7 +/** $factoryInfo + * @define Coll LinkedHashMap + * @define coll linked hash map */ object LinkedHashMap extends MutableMapFactory[LinkedHashMap] { implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), LinkedHashMap[A, B]] = new MapCanBuildFrom[A, B] def empty[A, B] = new LinkedHashMap[A, B] } -/** - * @since 2.7 +/** This class implements mutable maps using a hashtable. + * The iterator and all traversal methods of this class visit elements in the order they were inserted. + * + * @tparam A the type of the keys contained in this hash map. + * @tparam B the type of the values assigned to keys in this hash map. + * + * @define Coll LinkedHashMap + * @define coll linked hash map + * @define thatinfo the class of the returned collection. In the standard library configuration, + * `That` is always `LinkedHashMap[A, B]` if the elements contained in the resulting collection are + * pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[LinkedHashMap, (A, B), LinkedHashMap[A, B]]` + * is defined in object `LinkedHashMap`. Otherwise, `That` resolves to the most specific type that doesn't have + * to contain pairs of type `(A, B)`, which is `Iterable`. + * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the + * result class `That` from the current representation type `Repr` + * and the new element type `B`. This is usually the `canBuildFrom` value + * defined in object `LinkedHashMap`. + * @define mayNotTerminateInf + * @define willNotTerminateInf + * @define orderDependent + * @define orderDependentFold */ @serializable @SerialVersionUID(1L) class LinkedHashMap[A, B] extends Map[A, B] diff --git a/src/library/scala/collection/mutable/LinkedHashSet.scala b/src/library/scala/collection/mutable/LinkedHashSet.scala index 54338f61c9..7ecb71e23b 100644 --- a/src/library/scala/collection/mutable/LinkedHashSet.scala +++ b/src/library/scala/collection/mutable/LinkedHashSet.scala @@ -13,9 +13,29 @@ package mutable import generic._ -/** Todo: this has O(n) cost for element removal. - * Should be rewritten to be more efficient. - * @since 2.2 +/** This class implements mutable sets using a hashtable. + * The iterator and all traversal methods of this class visit elements in the order they were inserted. + * + * @author Matthias Zenger + * @author Martin Odersky + * @version 2.0, 31/12/2006 + * @since 1 + * + * @tparam A the type of the elements contained in this set. + * + * @define Coll LinkedHashSet + * @define coll linked hash set + * @define thatinfo the class of the returned collection. In the standard library configuration, + * `That` is always `LinkedHashSet[B]` because an implicit of type `CanBuildFrom[LinkedHashSet, B, LinkedHashSet[B]]` + * is defined in object `LinkedHashSet`. + * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the + * result class `That` from the current representation type `Repr` + * and the new element type `B`. This is usually the `canBuildFrom` value + * defined in object `LinkedHashSet`. + * @define mayNotTerminateInf + * @define willNotTerminateInf + * @define orderDependent + * @define orderDependentFold */ @serializable @SerialVersionUID(1L) class LinkedHashSet[A] extends Set[A] @@ -63,7 +83,10 @@ class LinkedHashSet[A] extends Set[A] } } -/** Factory object for `LinkedHashSet` class */ +/** $factoryInfo + * @define Coll LinkedHashSet + * @define coll linked hash set + */ object LinkedHashSet extends SetFactory[LinkedHashSet] { implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, LinkedHashSet[A]] = setCanBuildFrom[A] override def empty[A]: LinkedHashSet[A] = new LinkedHashSet[A] diff --git a/src/library/scala/collection/mutable/LinkedList.scala b/src/library/scala/collection/mutable/LinkedList.scala index 5570e80b22..a72acf1438 100644 --- a/src/library/scala/collection/mutable/LinkedList.scala +++ b/src/library/scala/collection/mutable/LinkedList.scala @@ -14,13 +14,29 @@ package mutable import generic._ -/** This class implements single linked lists where both the head (<code>elem</code>) - * and the tail (<code>next</code>) are mutable. +/** This class implements single linked lists where both the head (`elem`) + * and the tail (`next`) are mutable. * * @author Matthias Zenger * @author Martin Odersky * @version 2.8 * @since 1 + * + * @tparam A the type of the elements contained in this linked list. + * + * @define Coll LinkedList + * @define coll linked list + * @define thatinfo the class of the returned collection. In the standard library configuration, + * `That` is always `LinkedList[B]` because an implicit of type `CanBuildFrom[LinkedList, B, LinkedList[B]]` + * is defined in object `LinkedList`. + * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the + * result class `That` from the current representation type `Repr` + * and the new element type `B`. This is usually the `canBuildFrom` value + * defined in object `LinkedList`. + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @SerialVersionUID(-7308240733518833071L) class LinkedList[A]() extends LinearSeq[A] @@ -39,6 +55,10 @@ class LinkedList[A]() extends LinearSeq[A] override def companion: GenericCompanion[LinkedList] = LinkedList } +/** $factoryInfo + * @define Coll LinkedList + * @define coll linked list + */ object LinkedList extends SeqFactory[LinkedList] { override def empty[A]: LinkedList[A] = new LinkedList[A] diff --git a/src/library/scala/collection/mutable/LinkedListLike.scala b/src/library/scala/collection/mutable/LinkedListLike.scala index 2523ece370..4f1a878e02 100644 --- a/src/library/scala/collection/mutable/LinkedListLike.scala +++ b/src/library/scala/collection/mutable/LinkedListLike.scala @@ -16,13 +16,20 @@ import generic._ import annotation.tailrec /** This extensible class may be used as a basis for implementing linked - * list. Type variable <code>A</code> refers to the element type of the - * list, type variable <code>This</code> is used to model self types of + * list. Type variable `A` refers to the element type of the + * list, type variable `This` is used to model self types of * linked lists. + * * @author Matthias Zenger * @author Martin Odersky - * @version 2.8 + * @version 1.0, 08/07/2003 * @since 2.8 + * + * @tparam A type of the elements contained in the linked list + * @tparam This the type of the actual linked list holding the elements + * + * @define Coll LinkedList + * @define coll linked list */ trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends SeqLike[A, This] { self => diff --git a/src/library/scala/collection/mutable/ListBuffer.scala b/src/library/scala/collection/mutable/ListBuffer.scala index b8e5aeb262..a2611a8c0f 100644 --- a/src/library/scala/collection/mutable/ListBuffer.scala +++ b/src/library/scala/collection/mutable/ListBuffer.scala @@ -15,13 +15,29 @@ package mutable import generic._ import immutable.{List, Nil, ::} -/** A Buffer implementation back up by a list. It provides constant time +/** A `Buffer` implementation back up by a list. It provides constant time * prepend and append. Most other operations are linear. * * @author Matthias Zenger * @author Martin Odersky * @version 2.8 * @since 1 + * + * @tparam A the type of this list buffer's elements. + * + * @define Coll ListBuffer + * @define coll list buffer + * @define thatinfo the class of the returned collection. In the standard library configuration, + * `That` is always `ListBuffer[B]` because an implicit of type `CanBuildFrom[ListBuffer, B, ListBuffer[B]]` + * is defined in object `ListBuffer`. + * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the + * result class `That` from the current representation type `Repr` + * and the new element type `B`. This is usually the `canBuildFrom` value + * defined in object `ListBuffer`. + * @define orderDependent + * @define orderDependentFold + * @define mayNotTerminateInf + * @define willNotTerminateInf */ @serializable @SerialVersionUID(3419063961353022661L) final class ListBuffer[A] @@ -42,7 +58,9 @@ final class ListBuffer[A] protected def underlying: immutable.Seq[A] = start - /** The current length of the buffer + /** The current length of the buffer. + * + * This operation takes constant time. */ override def length = len @@ -52,13 +70,13 @@ final class ListBuffer[A] if (n < 0 || n >= len) throw new IndexOutOfBoundsException(n.toString()) else super.apply(n) - /** Replaces element at index <code>n</code> with the new element - * <code>newelem</code>. Takes time linear in the buffer size. (except the + /** Replaces element at index `n` with the new element + * `newelem`. Takes time linear in the buffer size. (except the * first element, which is updated in constant time). * * @param n the index of the element to replace. * @param x the new element. - * @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds. + * @throws Predef.IndexOutOfBoundsException if `n` is out of bounds. */ def update(n: Int, x: A) { try { @@ -90,6 +108,7 @@ final class ListBuffer[A] /** Appends a single element to this buffer. This operation takes constant time. * * @param x the element to append. + * @return this $coll. */ def += (x: A): this.type = { if (exported) copy() @@ -117,7 +136,7 @@ final class ListBuffer[A] * time. * * @param x the element to prepend. - * @return this buffer. + * @return this $coll. */ def +=: (x: A): this.type = { if (exported) copy() @@ -128,13 +147,13 @@ final class ListBuffer[A] this } - /** Inserts new elements at the index <code>n</code>. Opposed to method - * <code>update</code>, this method will not replace an element with a new - * one. Instead, it will insert a new element at index <code>n</code>. + /** Inserts new elements at the index `n`. Opposed to method + * `update`, this method will not replace an element with a new + * one. Instead, it will insert a new element at index `n`. * * @param n the index where a new element will be inserted. * @param iter the iterable object providing all elements to insert. - * @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds. + * @throws Predef.IndexOutOfBoundsException if `n` is out of bounds. */ def insertAll(n: Int, seq: Traversable[A]) { try { @@ -230,9 +249,9 @@ final class ListBuffer[A] * the buffer size * * @param n the index which refers to the element to delete. - * @return n the element that was formerly at position <code>n</code>. - * @note an element must exists at position <code>n</code> - * @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds. + * @return n the element that was formerly at position `n`. + * @note an element must exists at position `n`. + * @throws Predef.IndexOutOfBoundsException if `n` is out of bounds. */ def remove(n: Int): A = { if (n < 0 || n >= len) throw new IndexOutOfBoundsException(n.toString()) @@ -259,6 +278,7 @@ final class ListBuffer[A] * buffer size. * * @param x the element to remove. + * @return this $coll. */ override def -= (elem: A): this.type = { if (exported) copy() @@ -328,10 +348,9 @@ final class ListBuffer[A] override def stringPrefix: String = "ListBuffer" } -/** Factory object for <code>ListBuffer</code> class. - * - * @author Martin Odersky - * @version 2.8 +/** $factoryInfo + * @define Coll ListBuffer + * @define coll list buffer */ object ListBuffer extends SeqFactory[ListBuffer] { implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ListBuffer[A]] = new GenericCanBuildFrom[A] diff --git a/src/library/scala/collection/mutable/ListMap.scala b/src/library/scala/collection/mutable/ListMap.scala index c96873c81d..a4321d3818 100644 --- a/src/library/scala/collection/mutable/ListMap.scala +++ b/src/library/scala/collection/mutable/ListMap.scala @@ -14,8 +14,26 @@ package mutable import generic._ -/** A simple map backed by a list. - * @since 2.8 +/** A simple mutable map backed by a list. + * + * @tparam A the type of the keys contained in this list map. + * @tparam B the type of the values assigned to keys in this list map. + * + * @define Coll mutable.ListMap + * @define coll mutable list map + * @define thatinfo the class of the returned collection. In the standard library configuration, + * `That` is always `ListMap[A, B]` if the elements contained in the resulting collection are + * pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[ListMap, (A, B), ListMap[A, B]]` + * is defined in object `ListMap`. Otherwise, `That` resolves to the most specific type that doesn't have + * to contain pairs of type `(A, B)`, which is `Iterable`. + * @define $bfinfo an implicit value of class `CanBuildFrom` which determines the + * result class `That` from the current representation type `Repr` + * and the new element type `B`. This is usually the `canBuildFrom` value + * defined in object `ListMap`. + * @define mayNotTerminateInf + * @define willNotTerminateInf + * @define orderDependent + * @define orderDependentFold */ @serializable class ListMap[A, B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] { @@ -40,10 +58,9 @@ class ListMap[A, B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] { override def size: Int = siz } -/** This class implements mutable maps using a list. - * - * @author Martin Odersky - * @version 2.8 +/** $factoryInfo + * @define Coll ListMap + * @define coll list map */ object ListMap extends MutableMapFactory[ListMap] { implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] = new MapCanBuildFrom[A, B] |