From 67a63278a6c4e9347792219086f11a87d177eee7 Mon Sep 17 00:00:00 2001 From: Paul Phillips Date: Fri, 29 Jul 2011 23:58:45 +0000 Subject: - Update Scaladoc for LinkedList and for some o... - Update Scaladoc for LinkedList and for some of the functions/operators - that it inherits. Completed Scaladoc for append Added example - in GenSeqLike for apply. Added $collectExample to collect in - GenTraversableLike and supplied an actual example in LinkedList Contributed by Donald McLean. --- src/library/scala/collection/GenSeqLike.scala | 42 ++++++++++ .../scala/collection/GenTraversableLike.scala | 25 +++++- .../scala/collection/GenTraversableOnce.scala | 41 ++++++++- src/library/scala/collection/TraversableLike.scala | 43 +++++++++- src/library/scala/collection/TraversableOnce.scala | 39 +++++++++ .../scala/collection/mutable/LinkedList.scala | 98 ++++++++++++++++------ .../scala/collection/mutable/LinkedListLike.scala | 63 +++++++++++--- 7 files changed, 311 insertions(+), 40 deletions(-) diff --git a/src/library/scala/collection/GenSeqLike.scala b/src/library/scala/collection/GenSeqLike.scala index 56034273f0..57e5105e23 100644 --- a/src/library/scala/collection/GenSeqLike.scala +++ b/src/library/scala/collection/GenSeqLike.scala @@ -33,6 +33,16 @@ import annotation.bridge trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Parallelizable[A, parallel.ParSeq[A]] { /** Selects an element by its index in the $coll. + * + * Example: + * + * {{{ + * scala> val x = LinkedList(1, 2, 3, 4, 5) + * x: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4, 5) + * + * scala> x(3) + * res1: Int = 4 + * }}} * * @param idx The index to select. * @return the element of this $coll at index `idx`, where `0` indicates the first element. @@ -263,6 +273,22 @@ trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Pa def updated[B >: A, That](index: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That /** A copy of the $coll with an element prepended. + * + * Note that :-ending operators are right associative (see example). + * Also, the original $coll is not modified, so you will want to capture the result. + * + * Example: + * {{{ + * scala> val x = LinkedList(1) + * x: scala.collection.mutable.LinkedList[Int] = LinkedList(1) + * + * scala> val y = 2 +: x + * y: scala.collection.mutable.LinkedList[Int] = LinkedList(2, 1) + * + * scala> println(x) + * LinkedList(1) + * }}} + * * @param elem the prepended element * @tparam B the element type of the returned $coll. * @tparam That $thatinfo @@ -276,6 +302,7 @@ trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Pa def +:[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That /** A copy of this $coll with an element appended. + * * $willNotTerminateInf * @param elem the appended element * @tparam B the element type of the returned $coll. @@ -286,10 +313,25 @@ trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Pa * @usecase def :+(elem: A): $Coll[A] * @return a new $coll consisting of * all elements of this $coll followed by `elem`. + * @example + * {{{ + * scala> import scala.collection.mutable.LinkedList + * import scala.collection.mutable.LinkedList + * + * scala> val a = LinkedList(1) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1) + * + * scala> val b = a :+ 2 + * b: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * + * scala> println(a) + * LinkedList(1) + * }}} */ def :+[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That /** A copy of this $coll with an element value appended until a given target length is reached. + * * @param len the target length * @param elem the padding value * @tparam B the element type of the returned $coll. diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala index fbb8b96ba4..dc89bcf85d 100644 --- a/src/library/scala/collection/GenTraversableLike.scala +++ b/src/library/scala/collection/GenTraversableLike.scala @@ -45,6 +45,7 @@ import annotation.migration * * @define Coll GenTraversable * @define coll general collection + * @define collectExample * @tparam A the collection element type. * @tparam Repr the actual type of the element container. * @@ -160,6 +161,8 @@ trait GenTraversableLike[+A, +Repr] extends GenTraversableOnce[A] with Paralleli /** Builds a new collection by applying a partial function to all elements of this $coll * on which the function is defined. * + * $collectExample + * * @param pf the partial function which filters and maps the $coll. * @tparam B the element type of the returned collection. * @tparam That $thatinfo @@ -193,7 +196,27 @@ trait GenTraversableLike[+A, +Repr] extends GenTraversableOnce[A] with Paralleli */ def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That - /** Concatenates this $coll with the elements of a traversable collection. + /** Returns a new $coll containing the elements from the left hand operand followed by the elements from the + * right hand operand. The element type of the $coll is the most specific superclass encompassing + * the element types of the two operands (see example). + * + * Example: + * {{{ + * scala> val a = LinkedList(1) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1) + * + * scala> val b = LinkedList(2) + * b: scala.collection.mutable.LinkedList[Int] = LinkedList(2) + * + * scala> val c = a ++ b + * c: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * + * scala> val d = LinkedList('a') + * d: scala.collection.mutable.LinkedList[Char] = LinkedList(a) + * + * scala> val e = c ++ d + * e: scala.collection.mutable.LinkedList[AnyVal] = LinkedList(1, 2, a) + * }}} * * @param that the traversable to append. * @tparam B the element type of the returned collection. diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala index 5045d4b829..3e42e7812b 100644 --- a/src/library/scala/collection/GenTraversableOnce.scala +++ b/src/library/scala/collection/GenTraversableOnce.scala @@ -114,7 +114,16 @@ trait GenTraversableOnce[+A] { */ def fold[A1 >: A](z: A1)(op: (A1, A1) => A1): A1 - /** A syntactic sugar for out of order folding. See `fold`. */ + /** A syntactic sugar for out of order folding. See `fold`. + * + * Example: + * {{{ + * scala> val a = LinkedList(1,2,3,4) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4) + * + * scala> val b = (a /:\ 5)(_+_) + * b: Int = 15 + * }}}*/ def /:\[A1 >: A](z: A1)(op: (A1, A1) => A1): A1 = fold(z)(op) /** Applies a binary operator to a start value and all elements of this $coll, @@ -122,6 +131,21 @@ trait GenTraversableOnce[+A] { * * Note: `/:` is alternate syntax for `foldLeft`; `z /: xs` is the same as * `xs foldLeft z`. + * + * Examples: + * + * Note that the folding function used to compute b is equivalent to that used to compute c. + * {{{ + * scala> val a = LinkedList(1,2,3,4) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4) + * + * scala> val b = (5 /: a)(_+_) + * b: Int = 15 + * + * scala> val c = (5 /: a)((x,y) => x + y) + * c: Int = 15 + * }}} + * $willNotTerminateInf * $orderDependentFold * @@ -145,6 +169,21 @@ trait GenTraversableOnce[+A] { * $willNotTerminateInf * $orderDependentFold * + * Examples: + * + * Note that the folding function used to compute b is equivalent to that used to compute c. + * {{{ + * scala> val a = LinkedList(1,2,3,4) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4) + * + * scala> val b = (a :\ 5)(_+_) + * b: Int = 15 + * + * scala> val c = (a :\ 5)((x,y) => x + y) + * c: Int = 15 + * + * }}} + * * @param z the start value * @param op the binary operator * @tparam B the result type of the binary operator. diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala index 1f6c6ff0bb..e3d51fde4e 100644 --- a/src/library/scala/collection/TraversableLike.scala +++ b/src/library/scala/collection/TraversableLike.scala @@ -157,10 +157,22 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] def ++[B >: A, That](that: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = ++(that: GenTraversableOnce[B])(bf) - /** Concatenates this $coll with the elements of a traversable collection. + /** As with `++`, returns a new collection containing the elements from the left operand followed by the + * elements from the right operand. * It differs from `++` in that the right operand determines the type of * the resulting collection rather than the left one. * + * Example: + * {{{ + * scala> val x = List(1) + * x: List[Int] = List(1) + * + * scala> val y = LinkedList(2) + * y: scala.collection.mutable.LinkedList[Int] = LinkedList(2) + * + * scala> val z = x ++: y + * z: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * }}} * @param that the traversable to append. * @tparam B the element type of the returned collection. * @tparam That $thatinfo @@ -181,12 +193,39 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] b.result } - /** This overload exists because: for the implementation of `++`: we should + /** As with `++`, returns a new collection containing the elements from the left operand followed by the + * elements from the right operand. + * It differs from `++` in that the right operand determines the type of + * the resulting collection rather than the left one. + * + * Example: + * {{{ + * scala> val x = List(1) + * x: List[Int] = List(1) + * + * scala> val y = LinkedList(2) + * y: scala.collection.mutable.LinkedList[Int] = LinkedList(2) + * + * scala> val z = x ++: y + * z: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * }}} + * + * This overload exists because: for the implementation of `++:` we should * reuse that of `++` because many collections override it with more * efficient versions. * * Since `TraversableOnce` has no `++` method, we have to implement that * directly, but `Traversable` and down can use the overload. + * + * @param that the traversable to append. + * @tparam B the element type of the returned collection. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new collection of type `That` which contains all elements + * of this $coll followed by all elements of `that`. + * + * @return a new $coll which contains all elements of this $coll + * followed by all elements of `that`. */ def ++:[B >: A, That](that: Traversable[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = (that ++ seq)(breakOut) diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala index 01619b0ab0..4f125b4090 100644 --- a/src/library/scala/collection/TraversableOnce.scala +++ b/src/library/scala/collection/TraversableOnce.scala @@ -271,6 +271,19 @@ trait TraversableOnce[+A] extends GenTraversableOnce[A] { * Inside, the string representations (w.r.t. the method `toString`) * of all elements of this $coll are separated by the string `sep`. * + * Example: + * + * {{{ + * scala> val a = LinkedList(1,2,3,4) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4) + * + * scala> val b = new StringBuilder() + * b: StringBuilder = + * + * scala> a.addString(b, "LinkedList(", ", ", ")") + * res1: StringBuilder = LinkedList(1, 2, 3, 4) + * }}} + * * @param b the string builder to which elements are appended. * @param start the starting string. * @param sep the separator string. @@ -300,6 +313,19 @@ trait TraversableOnce[+A] extends GenTraversableOnce[A] { * The written text consists of the string representations (w.r.t. the method `toString`) * of all elements of this $coll, separated by the string `sep`. * + * Example: + * + * {{{ + * scala> val a = LinkedList(1,2,3,4) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4) + * + * scala> val b = new StringBuilder() + * b: StringBuilder = + * + * scala> a.addString(b, ", ") + * res0: StringBuilder = 1, 2, 3, 4 + * }}} + * * @param b the string builder to which elements are appended. * @param sep the separator string. * @return the string builder `b` to which elements were appended. @@ -310,6 +336,19 @@ trait TraversableOnce[+A] extends GenTraversableOnce[A] { * The written text consists of the string representations (w.r.t. the method * `toString`) of all elements of this $coll without any separator string. * + * Example: + * + * {{{ + * scala> val a = LinkedList(1,2,3,4) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4) + * + * scala> val b = new StringBuilder() + * b: StringBuilder = + * + * scala> val h = a.addString(b) + * b: StringBuilder = 1234 + * }}} + * @param b the string builder to which elements are appended. * @return the string builder `b` to which elements were appended. */ diff --git a/src/library/scala/collection/mutable/LinkedList.scala b/src/library/scala/collection/mutable/LinkedList.scala index bfb2db2b34..6c4372cbb4 100644 --- a/src/library/scala/collection/mutable/LinkedList.scala +++ b/src/library/scala/collection/mutable/LinkedList.scala @@ -13,30 +13,65 @@ package mutable import generic._ -/** 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 - */ +/** A more traditional/primitive style of linked list where the "list" is also the "head" link. Links can be manually + * created and manipulated, though the use of the API, when possible, is recommended. + * + * The danger of directly manipulating next: + * {{{ + * scala> val b = LinkedList(1) + * b: scala.collection.mutable.LinkedList[Int] = LinkedList(1) + * + * scala> b.next = null + * + * scala> println(b) + * java.lang.NullPointerException + * }}} + * + * $singleLinkedListExample + * + * @author Matthias Zenger + * @author Martin Odersky + * @version 2.8 + * @since 1 + * + * @tparam A the type of the elements contained in this linked list. + * + * @constructor Creates an "empty" list, defined as a single node with no data element and next pointing to itself. + + * @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 + * @define collectExample Example: + * {{{ + * scala> val a = LinkedList(1, 2, 3) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3) + * + * scala> val addOne: PartialFunction[Any, Float] = {case i: Int => i + 1.0f} + * addOne: PartialFunction[Any,Float] = + * + * scala> val b = a.collect(addOne) + * b: scala.collection.mutable.LinkedList[Float] = LinkedList(2.0, 3.0, 4.0) + * + * scala> val c = LinkedList('a') + * c: scala.collection.mutable.LinkedList[Char] = LinkedList(a) + * + * scala> val d = a ++ c + * d: scala.collection.mutable.LinkedList[AnyVal] = LinkedList(1, 2, 3, a) + * + * scala> val e = d.collect(addOne) + * e: scala.collection.mutable.LinkedList[Float] = LinkedList(2.0, 3.0, 4.0) + * }}} + */ @SerialVersionUID(-7308240733518833071L) class LinkedList[A]() extends LinearSeq[A] with GenericTraversableTemplate[A, LinkedList] @@ -44,6 +79,21 @@ class LinkedList[A]() extends LinearSeq[A] with Serializable { next = this + /** Creates a new list. If the parameter next is null, the result is an empty list. Otherwise, the result is + * a list with elem at the head, followed by the contents of next. + * + * Note that next is part of the new list, as opposed to the +: operator, + * which makes a new copy of the original list. + * + * @example + * {{{ + * scala> val m = LinkedList(1) + * m: scala.collection.mutable.LinkedList[Int] = LinkedList(1) + * + * scala> val n = new LinkedList[Int](2, m) + * n: scala.collection.mutable.LinkedList[Int] = LinkedList(2, 1) + * }}} + */ def this(elem: A, next: LinkedList[A]) { this() if (next != null) { diff --git a/src/library/scala/collection/mutable/LinkedListLike.scala b/src/library/scala/collection/mutable/LinkedListLike.scala index a3fd786c2a..0f977c0a17 100644 --- a/src/library/scala/collection/mutable/LinkedListLike.scala +++ b/src/library/scala/collection/mutable/LinkedListLike.scala @@ -19,6 +19,20 @@ import annotation.tailrec * list, type variable `This` is used to model self types of * linked lists. * + * $singleLinkedListExample + * + * @author Matthias Zenger + * @author Martin Odersky + * @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 + * + * @define singleLinkedListExample * If the list is empty `next` must be set to `this`. The last node in every * mutable linked list is empty. * @@ -42,17 +56,6 @@ import annotation.tailrec * [ ] <-` * * }}} - * - * @author Matthias Zenger - * @author Martin Odersky - * @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 => @@ -60,6 +63,10 @@ trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends Seq var next: This = _ override def isEmpty = next eq this + + /** Determines the length of this $coll by traversing and counting every + * node. + */ override def length: Int = length0(repr, 0) @tailrec private def length0(elem: This, acc: Int): Int = @@ -74,7 +81,39 @@ trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends Seq next } - /** Append linked list `that` at current position of this linked list + /** If `this` is empty then it does nothing and returns `that`. Otherwise, appends `that` to `this`. The append + * requires a full traversal of `this`. + * + * Examples: + * + * {{{ + * scala> val a = LinkedList(1, 2) + * a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * + * scala> val b = LinkedList(1, 2) + * b: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * + * scala> a.append(b) + * res0: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 1, 2) + * + * scala> println(a) + * LinkedList(1, 2, 1, 2) + * }}} + * + * {{{ + * scala> val a = new LinkedList[Int]() + * a: scala.collection.mutable.LinkedList[Int] = LinkedList() + * + * scala> val b = LinkedList(1, 2) + * b: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * + * scala> val c = a.append(b) + * c: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2) + * + * scala> println(a) + * LinkedList() + * }}} + * * @return the list after append (this is the list itself if nonempty, * or list `that` if list this is empty. ) */ -- cgit v1.2.3