diff options
author | Aleksandar Pokopec <aleksandar.prokopec@epfl.ch> | 2011-04-14 16:09:33 +0000 |
---|---|---|
committer | Aleksandar Pokopec <aleksandar.prokopec@epfl.ch> | 2011-04-14 16:09:33 +0000 |
commit | 09e192caea0fe2b8afaed96a7077e8cf52af2345 (patch) | |
tree | 356cb0692eefc6703502339d271e7bcda9a437f1 | |
parent | 09028a4fa5cf66a98080baa26cdadba29314c640 (diff) | |
download | scala-09e192caea0fe2b8afaed96a7077e8cf52af2345.tar.gz scala-09e192caea0fe2b8afaed96a7077e8cf52af2345.tar.bz2 scala-09e192caea0fe2b8afaed96a7077e8cf52af2345.zip |
Adding some docs refactorings.
Also, added some docs variables to Gen* traits that were missing.
No review.
17 files changed, 1002 insertions, 925 deletions
diff --git a/src/library/scala/collection/GenIterableLike.scala b/src/library/scala/collection/GenIterableLike.scala index 61e8b0d349..94713228bf 100644 --- a/src/library/scala/collection/GenIterableLike.scala +++ b/src/library/scala/collection/GenIterableLike.scala @@ -16,20 +16,125 @@ import generic.{ CanBuildFrom => CBF, _ } * This trait contains abstract methods and methods that can be implemented * directly in terms of other methods. * + * @define Coll GenIterable + * @define coll general iterable collection + * * @author Martin Odersky * @author Aleksandar Prokopec * @since 2.9 + * @define zipthatinfo the class of the returned collection. Where possible, `That` is + * the same class as the current collection class `Repr`, but this + * depends on the element type `(A1, B)` being admissible for that class, + * which means that an implicit instance of type `CanBuildFrom[Repr, (A1, B), That]`. + * is found. + * @define zipbfinfo an implicit value of class `CanBuildFrom` which determines the + * result class `That` from the current representation type `Repr` + * and the new element type `(A1, B)`. + * @define iterableInfo + * This is a base trait for all Scala collections that define an `iterator` + * method to step through one-by-one the collection's elements. */ -trait GenIterableLike[+A, +Repr] extends GenTraversableLike[A, Repr] { +private[collection] trait GenIterableLike[+A, +Repr] extends GenTraversableLike[A, Repr] { def iterator: Iterator[A] + /** Checks if the other iterable collection contains the same elements in the same order as this $coll. + * + * $orderDependent + * $willNotTerminateInf + * + * @param that the collection to compare with. + * @tparam B the type of the elements of collection `that`. + * @return `true`, if both collections contain the same elements in the same order, `false` otherwise. + * + * @usecase def sameElements(that: Iterable[A]): Boolean + * + * @param that the collection to compare with. + * @return `true`, if both collections contain the same elements in the same order, `false` otherwise. + */ def sameElements[A1 >: A](that: GenIterable[A1]): Boolean + /** Returns a $coll formed from this $coll and another iterable collection + * by combining corresponding elements in pairs. + * If one of the two collections is longer than the other, its remaining elements are ignored. + * + * $orderDependent + * + * @param that The iterable providing the second half of each result pair + * @tparam A1 the type of the first half of the returned pairs (this is always a supertype + * of the collection's element type `A`). + * @tparam B the type of the second half of the returned pairs + * @tparam That $zipthatinfo + * @param bf $zipbfinfo + * @return a new collection of type `That` containing pairs consisting of + * corresponding elements of this $coll and `that`. The length + * of the returned collection is the minimum of the lengths of this $coll and `that`. + * + * @usecase def zip[B](that: Iterable[B]): $Coll[(A, B)] + * + * @param that The iterable providing the second half of each result pair + * @tparam B the type of the second half of the returned pairs + * @return a new $coll containing pairs consisting of + * corresponding elements of this $coll and `that`. The length + * of the returned collection is the minimum of the lengths of this $coll and `that`. + */ def zip[A1 >: A, B, That](that: GenIterable[B])(implicit bf: CBF[Repr, (A1, B), That]): That + /** Zips this $coll with its indices. + * + * $orderDependent + * + * @tparam A1 the type of the first half of the returned pairs (this is always a supertype + * of the collection's element type `A`). + * @tparam That the class of the returned collection. Where possible, `That` is + * the same class as the current collection class `Repr`, but this + * depends on the element type `(A1, Int)` being admissible for that class, + * which means that an implicit instance of type `CanBuildFrom[Repr, (A1, Int), That]`. + * is found. + * @tparam bf an implicit value of class `CanBuildFrom` which determines the + * result class `That` from the current representation type `Repr` + * and the new element type `(A1, Int)`. + * @return A new collection of type `That` containing pairs consisting of all elements of this + * $coll paired with their index. Indices start at `0`. + * + * @usecase def zipWithIndex: $Coll[(A, Int)] + * + * @return A new $coll containing pairs consisting of all elements of this + * $coll paired with their index. Indices start at `0`. + * @example + * `List("a", "b", "c").zipWithIndex = List(("a", 0), ("b", 1), ("c", 2))` + * + */ def zipWithIndex[A1 >: A, That](implicit bf: CBF[Repr, (A1, Int), That]): That + /** Returns a $coll formed from this $coll and another iterable collection + * by combining corresponding elements in pairs. + * If one of the two collections is shorter than the other, + * placeholder elements are used to extend the shorter collection to the length of the longer. + * + * $orderDependent + * + * @param that the iterable providing the second half of each result pair + * @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`. + * @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll. + * @return a new collection of type `That` containing pairs consisting of + * corresponding elements of this $coll and `that`. The length + * of the returned collection is the maximum of the lengths of this $coll and `that`. + * If this $coll is shorter than `that`, `thisElem` values are used to pad the result. + * If `that` is shorter than this $coll, `thatElem` values are used to pad the result. + * + * @usecase def zipAll[B](that: Iterable[B], thisElem: A, thatElem: B): $Coll[(A, B)] + * + * @param that The iterable providing the second half of each result pair + * @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`. + * @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll. + * @tparam B the type of the second half of the returned pairs + * @return a new $coll containing pairs consisting of + * corresponding elements of this $coll and `that`. The length + * of the returned collection is the maximum of the lengths of this $coll and `that`. + * If this $coll is shorter than `that`, `thisElem` values are used to pad the result. + * If `that` is shorter than this $coll, `thatElem` values are used to pad the result. + */ def zipAll[B, A1 >: A, That](that: GenIterable[B], thisElem: A1, thatElem: B)(implicit bf: CBF[Repr, (A1, B), That]): That def isEmpty = iterator.isEmpty diff --git a/src/library/scala/collection/GenIterableViewLike.scala b/src/library/scala/collection/GenIterableViewLike.scala index 9e3927eaf4..c3f0adc310 100644 --- a/src/library/scala/collection/GenIterableViewLike.scala +++ b/src/library/scala/collection/GenIterableViewLike.scala @@ -15,9 +15,9 @@ import TraversableView.NoBuilder -trait GenIterableViewLike[+A, - +Coll, - +This <: GenIterableView[A, Coll] with GenIterableViewLike[A, Coll, This]] +private[collection] trait GenIterableViewLike[+A, + +Coll, + +This <: GenIterableView[A, Coll] with GenIterableViewLike[A, Coll, This]] extends GenIterable[A] with GenIterableLike[A, This] with GenTraversableView[A, Coll] with GenTraversableViewLike[A, Coll, This] { self => diff --git a/src/library/scala/collection/GenMapLike.scala b/src/library/scala/collection/GenMapLike.scala index 5631ae96d4..9ae388afb4 100644 --- a/src/library/scala/collection/GenMapLike.scala +++ b/src/library/scala/collection/GenMapLike.scala @@ -11,11 +11,17 @@ package scala.collection /** A trait for all maps upon which operations may be * implemented in parallel. * + * @define Coll GenMap + * @define coll general map * @author Martin Odersky * @author Aleksandar Prokopec * @since 2.9 + * @define mapNote + * + * A map is a collection of bindings from keys to values, where there are + * no duplicate keys. */ -trait GenMapLike[A, +B, +Repr] extends GenIterableLike[(A, B), Repr] with Equals with Parallelizable[(A, B), parallel.ParMap[A, B]] { +private[collection] trait GenMapLike[A, +B, +Repr] extends GenIterableLike[(A, B), Repr] with Equals with Parallelizable[(A, B), parallel.ParMap[A, B]] { def default(key: A): B def get(key: A): Option[B] def apply(key: A): B diff --git a/src/library/scala/collection/GenSeqLike.scala b/src/library/scala/collection/GenSeqLike.scala index 8dcd5936d5..61902bea37 100644 --- a/src/library/scala/collection/GenSeqLike.scala +++ b/src/library/scala/collection/GenSeqLike.scala @@ -13,6 +13,8 @@ import generic._ /** A template trait for all sequences which may be traversed * in parallel. * + * @define Coll GenSeq + * @define coll general sequence * @define mayNotTerminateInf * * Note: may not terminate for infinite-sized collections. @@ -23,53 +25,296 @@ import generic._ * @author Martin Odersky * @author Aleksandar Prokopec * @since 2.9 + * @define seqInfo + * Sequences are special cases of iterable collections of class `Iterable`. + * Unlike iterables, sequences always have a defined order of elements. */ -trait GenSeqLike[+T, +Repr] extends GenIterableLike[T, Repr] with Equals with Parallelizable[T, parallel.ParSeq[T]] { +private[collection] trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Parallelizable[A, parallel.ParSeq[A]] { - def apply(idx: Int): T + /** Selects an element by its index in the $coll. + * + * @param idx The index to select. + * @return the element of this $coll at index `idx`, where `0` indicates the first element. + * @throws `IndexOutOfBoundsException` if `idx` does not satisfy `0 <= idx < length`. + */ + def apply(idx: Int): A + /** The length of the $coll. + * + * $willNotTerminateInf + * + * Note: `xs.length` and `xs.size` yield the same result. + * + * @return the number of elements in this $coll. + */ def length: Int - def segmentLength(p: T => Boolean, from: Int): Int - - def prefixLength(p: T => Boolean): Int + /** Tests whether this $coll contains given index. + * + * The implementations of methods `apply` and `isDefinedAt` turn a `Seq[A]` into + * a `PartialFunction[Int, A]`. + * + * @param idx the index to test + * @return `true` if this $coll contains an element at position `idx`, `false` otherwise. + */ + def isDefinedAt(idx: Int): Boolean = (idx >= 0) && (idx < length) - def indexWhere(p: T => Boolean, from: Int): Int + /** Computes length of longest segment whose elements all satisfy some predicate. + * + * $mayNotTerminateInf + * + * @param p the predicate used to test elements. + * @param from the index where the search starts. + * @return the length of the longest segment of this $coll starting from index `from` + * such that every element of the segment satisfies the predicate `p`. + */ + def segmentLength(p: A => Boolean, from: Int): Int - def indexWhere(p: T => Boolean): Int + /** Returns the length of the longest prefix whose elements all satisfy some predicate. + * + * $mayNotTerminateInf + * + * @param p the predicate used to test elements. + * @return the length of the longest prefix of this $coll + * such that every element of the segment satisfies the predicate `p`. + */ + def prefixLength(p: A => Boolean): Int = segmentLength(p, 0) - def findIndexOf(p: T => Boolean): Int + /** Finds index of the first element satisfying some predicate after or at some start index. + * + * $mayNotTerminateInf + * + * @param p the predicate used to test elements. + * @param from the start index + * @return the index `>= from` of the first element of this $coll that satisfies the predicate `p`, + * or `-1`, if none exists. + */ + def indexWhere(p: A => Boolean, from: Int): Int - def indexOf[U >: T](elem: U): Int + /** Finds index of first element satisfying some predicate. + * + * $mayNotTerminateInf + * + * @param p the predicate used to test elements. + * @return the index of the first element of this $coll that satisfies the predicate `p`, + * or `-1`, if none exists. + */ + def indexWhere(p: A => Boolean): Int = indexWhere(p, 0) - def indexOf[U >: T](elem: U, from: Int): Int + /** Finds index of first occurrence of some value in this $coll. + * + * $mayNotTerminateInf + * + * @param elem the element value to search for. + * @tparam B the type of the element `elem`. + * @return the index of the first element of this $coll that is equal (wrt `==`) + * to `elem`, or `-1`, if none exists. + * + * @usecase def indexOf(elem: A): Int + */ + def indexOf[B >: A](elem: B): Int = indexOf(elem, 0) - def lastIndexWhere(p: T => Boolean, end: Int): Int + /** Finds index of first occurrence of some value in this $coll after or at some start index. + * + * $mayNotTerminateInf + * + * @param elem the element value to search for. + * @tparam B the type of the element `elem`. + * @param from the start index + * @return the index `>= from` of the first element of this $coll that is equal (wrt `==`) + * to `elem`, or `-1`, if none exists. + * + * @usecase def indexOf(elem: A, from: Int): Int + */ + def indexOf[B >: A](elem: B, from: Int): Int = indexWhere(elem ==, from) - def reverse: Repr + /** Finds index of last occurrence of some value in this $coll. + * + * $willNotTerminateInf + * + * @param elem the element value to search for. + * @tparam B the type of the element `elem`. + * @return the index of the last element of this $coll that is equal (wrt `==`) + * to `elem`, or `-1`, if none exists. + * + * @usecase def lastIndexOf(elem: A): Int + */ + def lastIndexOf[B >: A](elem: B): Int = lastIndexWhere(elem ==) - def reverseMap[S, That](f: T => S)(implicit bf: CanBuildFrom[Repr, S, That]): That + /** Finds index of last occurrence of some value in this $coll before or at a given end index. + * + * @param elem the element value to search for. + * @param end the end index. + * @tparam B the type of the element `elem`. + * @return the index `<= end` of the last element of this $coll that is equal (wrt `==`) + * to `elem`, or `-1`, if none exists. + * + * @usecase def lastIndexOf(elem: A, end: Int): Int + */ + def lastIndexOf[B >: A](elem: B, end: Int): Int = lastIndexWhere(elem ==, end) - def startsWith[S](that: GenSeq[S]): Boolean + /** Finds index of last element satisfying some predicate. + * + * $willNotTerminateInf + * + * @param p the predicate used to test elements. + * @return the index of the last element of this $coll that satisfies the predicate `p`, + * or `-1`, if none exists. + */ + def lastIndexWhere(p: A => Boolean): Int = lastIndexWhere(p, length - 1) - def startsWith[S](that: GenSeq[S], offset: Int): Boolean + /** Finds index of last element satisfying some predicate before or at given end index. + * + * @param p the predicate used to test elements. + * @return the index `<= end` of the last element of this $coll that satisfies the predicate `p`, + * or `-1`, if none exists. + */ + def lastIndexWhere(p: A => Boolean, end: Int): Int - def endsWith[S](that: GenSeq[S]): Boolean + /** Returns new $coll wih elements in reversed order. + * + * $willNotTerminateInf + * + * @return A new $coll with all elements of this $coll in reversed order. + */ + def reverse: Repr - def patch[U >: T, That](from: Int, patch: GenSeq[U], replaced: Int)(implicit bf: CanBuildFrom[Repr, U, That]): That + /** + * Builds a new collection by applying a function to all elements of this $coll and + * collecting the results in reversed order. + * + * $willNotTerminateInf + * + * Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient. + * + * @param f the function to apply to each element. + * @tparam B the element type of the returned collection. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new collection of type `That` resulting from applying the given function + * `f` to each element of this $coll and collecting the results in reversed order. + * + * @usecase def reverseMap[B](f: A => B): $Coll[B] + * + * Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient. + * @return a new $coll resulting from applying the given function + * `f` to each element of this $coll and collecting the results in reversed order. + */ + def reverseMap[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That - def updated[U >: T, That](index: Int, elem: U)(implicit bf: CanBuildFrom[Repr, U, That]): That + /** Tests whether this $coll starts with the given sequence. + * + * @param that the sequence to test + * @return `true` if this collection has `that` as a prefix, `false` otherwise. + */ + def startsWith[B](that: GenSeq[B]): Boolean = startsWith(that, 0) - def +:[U >: T, That](elem: U)(implicit bf: CanBuildFrom[Repr, U, That]): That + /** Tests whether this $coll contains the given sequence at a given index. + * + * If the both the receiver object, <code>this</code> and + * the argument, <code>that</code> are infinite sequences + * this method may not terminate. + * + * @param that the sequence to test + * @param offset the index where the sequence is searched. + * @return `true` if the sequence `that` is contained in this $coll at index `offset`, + * otherwise `false`. + */ + def startsWith[B](that: GenSeq[B], offset: Int): Boolean - def :+[U >: T, That](elem: U)(implicit bf: CanBuildFrom[Repr, U, That]): That + /** Tests whether this $coll ends with the given sequence. + * $willNotTerminateInf + * @param that the sequence to test + * @return `true` if this $coll has `that` as a suffix, `false` otherwise. + */ + def endsWith[B](that: GenSeq[B]): Boolean - def padTo[U >: T, That](len: Int, elem: U)(implicit bf: CanBuildFrom[Repr, U, That]): That + /** Produces a new $coll where a slice of elements in this $coll is replaced by another sequence. + * + * @param from the index of the first replaced element + * @param patch the replacement sequence + * @param replaced the number of elements to drop in the original $coll + * @tparam B the element type of the returned $coll. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new $coll consisting of all elements of this $coll + * except that `replaced` elements starting from `from` are replaced + * by `patch`. + * @usecase def patch(from: Int, that: Seq[A], replaced: Int): $Coll[A] + * @return a new $coll consisting of all elements of this $coll + * except that `replaced` elements starting from `from` are replaced + * by `patch`. + */ + def patch[B >: A, That](from: Int, patch: GenSeq[B], replaced: Int)(implicit bf: CanBuildFrom[Repr, B, That]): That + + /** A copy of this $coll with one single replaced element. + * @param index the position of the replacement + * @param elem the replacing element + * @tparam B the element type of the returned $coll. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new $coll` which is a copy of this $coll with the element at position `index` replaced by `elem`. + * @usecase def updated(index: Int, elem: A): $Coll[A] + * @return a copy of this $coll with the element at position `index` replaced by `elem`. + */ + def updated[B >: A, That](index: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That + + /** Prepends an element to this $coll + * @param elem the prepended element + * @tparam B the element type of the returned $coll. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new collection of type `That` consisting of `elem` followed + * by all elements of this $coll. + * @usecase def +:(elem: A): $Coll[A] + * @return a new $coll consisting of `elem` followed + * by all elements of this $coll. + */ + def +:[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That - def corresponds[S](that: GenSeq[S])(p: (T, S) => Boolean): Boolean + /** Appends an element to this $coll + * $willNotTerminateInf + * @param elem the appended element + * @tparam B the element type of the returned $coll. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new collection of type `That` consisting of + * all elements of this $coll followed by `elem`. + * @usecase def :+(elem: A): $Coll[A] + * @return a new $coll consisting of + * all elements of this $coll followed by `elem`. + */ + def :+[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That + + /** Appends an element value to this $coll 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. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new collection of type `That` consisting of + * all elements of this $coll followed by the minimal number of occurrences of `elem` so + * that the resulting collection has a length of at least `len`. + * @usecase def padTo(len: Int, elem: A): $Coll[A] + * @return a new $coll consisting of + * all elements of this $coll followed by the minimal number of occurrences of `elem` so + * that the resulting $coll has a length of at least `len`. + */ + def padTo[B >: A, That](len: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That - def toSeq: GenSeq[T] + /** Tests whether every element of this $coll relates to the + * corresponding element of another sequence by satisfying a test predicate. + * + * @param that the other sequence + * @param p the test predicate, which relates elements from both sequences + * @tparam B the type of the elements of `that` + * @return `true` if both sequences have the same length and + * `p(x, y)` is `true` for all corresponding elements `x` of this $coll + * and `y` of `that`, otherwise `false`. + */ + def corresponds[B](that: GenSeq[B])(p: (A, B) => Boolean): Boolean + def toSeq: GenSeq[A] /** Produces a new sequence which contains all elements of this $coll and also all elements of * a given sequence. `xs union ys` is equivalent to `xs ++ ys`. @@ -91,7 +336,7 @@ trait GenSeqLike[+T, +Repr] extends GenIterableLike[T, Repr] with Equals with Pa * @return a new $coll which contains all elements of this $coll * followed by all elements of `that`. */ - def union[U >: T, That](that: GenSeq[U])(implicit bf: CanBuildFrom[Repr, U, That]): That = this ++ that + def union[B >: A, That](that: GenSeq[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = this ++ that /** Computes the multiset difference between this $coll and another sequence. * $willNotTerminateInf @@ -112,7 +357,7 @@ trait GenSeqLike[+T, +Repr] extends GenIterableLike[T, Repr] with Equals with Pa * ''n'' times in `that`, then the first ''n'' occurrences of `x` will not form * part of the result, but any following occurrences will. */ - def diff[U >: T](that: GenSeq[U]): Repr + def diff[B >: A](that: GenSeq[B]): Repr /** Computes the multiset intersection between this $coll and another sequence. * $mayNotTerminateInf @@ -133,7 +378,7 @@ trait GenSeqLike[+T, +Repr] extends GenIterableLike[T, Repr] with Equals with Pa * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained * in the result, but any following occurrences will be omitted. */ - def intersect[U >: T](that: GenSeq[U]): Repr + def intersect[B >: A](that: GenSeq[B]): Repr /** Builds a new $coll from this $coll without any duplicate elements. * $willNotTerminateInf @@ -146,7 +391,7 @@ trait GenSeqLike[+T, +Repr] extends GenIterableLike[T, Repr] with Equals with Pa * elements of the $coll. */ override def hashCode() = { - val h = new util.MurmurHash[T](Seq.hashSeed) + val h = new util.MurmurHash[A](Seq.hashSeed) seq.foreach(h) h.hash } diff --git a/src/library/scala/collection/GenSeqViewLike.scala b/src/library/scala/collection/GenSeqViewLike.scala index 2f06a52cd3..74d558342f 100644 --- a/src/library/scala/collection/GenSeqViewLike.scala +++ b/src/library/scala/collection/GenSeqViewLike.scala @@ -11,9 +11,9 @@ package scala.collection -trait GenSeqViewLike[+A, - +Coll, - +This <: GenSeqView[A, Coll] with GenSeqViewLike[A, Coll, This]] +private[collection] trait GenSeqViewLike[+A, + +Coll, + +This <: GenSeqView[A, Coll] with GenSeqViewLike[A, Coll, This]] extends GenSeq[A] with GenSeqLike[A, This] with GenIterableView[A, Coll] with GenIterableViewLike[A, Coll, This] { self => diff --git a/src/library/scala/collection/GenSetLike.scala b/src/library/scala/collection/GenSetLike.scala index dc4a82688c..d45810d2e7 100644 --- a/src/library/scala/collection/GenSetLike.scala +++ b/src/library/scala/collection/GenSetLike.scala @@ -11,11 +11,16 @@ package scala.collection /** A template trait for sets which may possibly * have their operations implemented in parallel. * + * @define Coll GenSet + * @define coll general set * @author Martin Odersky * @author Aleksandar Prokopec * @since 2.9 + * @define setNote + * + * A set is a collection that contains no duplicate elements. */ -trait GenSetLike[A, +Repr] +private[collection] trait GenSetLike[A, +Repr] extends GenIterableLike[A, Repr] with (A => Boolean) with Equals diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala index c284efd9d4..558e528808 100644 --- a/src/library/scala/collection/GenTraversableLike.scala +++ b/src/library/scala/collection/GenTraversableLike.scala @@ -8,7 +8,10 @@ package scala.collection + import generic._ +import annotation.migration + /** A template trait for all traversable collections upon which operations * may be implemented in parallel. @@ -36,21 +39,26 @@ import generic._ * Note: will not terminate for infinite-sized collections. * * @define Coll GenTraversable - * @define coll collection - * @tparam T the collection element type. + * @define coll general collection + * @tparam A the collection element type. * @tparam Repr the actual type of the element container. * * @author Martin Odersky * @author Aleksandar Prokopec * @since 2.9 */ -trait GenTraversableLike[+T, +Repr] extends GenTraversableOnceLike[T] with Parallelizable[T, parallel.ParIterable[T]] { +private[collection] trait GenTraversableLike[+A, +Repr] extends GenTraversableOnceLike[A] with Parallelizable[A, parallel.ParIterable[A]] { def repr: Repr def size: Int - def head: T + def head: A + + /** Tests whether this $coll can be repeatedly traversed. + * @return `true` + */ + final def isTraversableAgain = true /** Selects all elements except the first. * $orderDependent @@ -67,57 +75,259 @@ trait GenTraversableLike[+T, +Repr] extends GenTraversableOnceLike[T] with Paral * * Note: The neutral element `z` may be applied more than once. * - * @tparam U element type of the resulting collection + * @tparam B element type of the resulting collection * @tparam That type of the resulting collection * @param z neutral element for the operator `op` * @param op the associative operator for the scan * @param cbf combiner factory which provides a combiner * @return a collection containing the prefix scan of the elements in the original collection * - * @usecase def scan(z: T)(op: (T, T) => T): $Coll[T] + * @usecase def scan(z: B)(op: (B, B) => B): $Coll[B] * * @return a new $coll containing the prefix scan of the elements in this $coll */ - def scan[U >: T, That](z: U)(op: (U, U) => U)(implicit cbf: CanBuildFrom[Repr, U, That]): That + def scan[B >: A, That](z: B)(op: (B, B) => B)(implicit cbf: CanBuildFrom[Repr, B, That]): That - def scanLeft[S, That](z: S)(op: (S, T) => S)(implicit bf: CanBuildFrom[Repr, S, That]): That + /** Produces a collection containing cummulative results of applying the + * operator going left to right. + * + * $willNotTerminateInf + * $orderDependent + * + * @tparam B the type of the elements in the resulting collection + * @tparam That the actual type of the resulting collection + * @param z the initial value + * @param op the binary operator applied to the intermediate result and the element + * @param bf $bfinfo + * @return collection with intermediate results + */ + def scanLeft[B, That](z: B)(op: (B, A) => B)(implicit bf: CanBuildFrom[Repr, B, That]): That - def scanRight[S, That](z: S)(op: (T, S) => S)(implicit bf: CanBuildFrom[Repr, S, That]): That + /** Produces a collection containing cummulative results of applying the operator going right to left. + * The head of the collection is the last cummulative result. + * $willNotTerminateInf + * $orderDependent + * + * Example: + * {{{ + * List(1, 2, 3, 4).scanRight(0)(_ + _) == List(10, 9, 7, 4, 0) + * }}} + * + * @tparam B the type of the elements in the resulting collection + * @tparam That the actual type of the resulting collection + * @param z the initial value + * @param op the binary operator applied to the intermediate result and the element + * @param bf $bfinfo + * @return collection with intermediate results + */ + @migration(2, 9, + "This scanRight definition has changed in 2.9.\n" + + "The previous behavior can be reproduced with scanRight.reverse." + ) + def scanRight[B, That](z: B)(op: (A, B) => B)(implicit bf: CanBuildFrom[Repr, B, That]): That - def foreach[U](f: T => U): Unit + /** Applies a function `f` to all elements of this $coll. + * + * @param f the function that is applied for its side-effect to every element. + * The result of function `f` is discarded. + * + * @tparam U the type parameter describing the result of function `f`. + * This result will always be ignored. Typically `U` is `Unit`, + * but this is not necessary. + * + * @usecase def foreach(f: A => Unit): Unit + */ + def foreach[U](f: A => U): Unit - def map[S, That](f: T => S)(implicit bf: CanBuildFrom[Repr, S, That]): That + /** Builds a new collection by applying a function to all elements of this $coll. + * + * @param f the function to apply to each element. + * @tparam B the element type of the returned collection. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new collection of type `That` resulting from applying the given function + * `f` to each element of this $coll and collecting the results. + * + * @usecase def map[B](f: A => B): $Coll[B] + * + * @return a new $coll resulting from applying the given function + * `f` to each element of this $coll and collecting the results. + */ + def map[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That - def collect[S, That](pf: PartialFunction[T, S])(implicit bf: CanBuildFrom[Repr, S, That]): That + /** Builds a new collection by applying a partial function to all elements of this $coll + * on which the function is defined. + * + * @param pf the partial function which filters and maps the $coll. + * @tparam B the element type of the returned collection. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new collection of type `That` resulting from applying the partial function + * `pf` to each element on which it is defined and collecting the results. + * The order of the elements is preserved. + * + * @usecase def collect[B](pf: PartialFunction[A, B]): $Coll[B] + * + * @return a new $coll resulting from applying the given partial function + * `pf` to each element on which it is defined and collecting the results. + * The order of the elements is preserved. + */ + def collect[B, That](pf: PartialFunction[A, B])(implicit bf: CanBuildFrom[Repr, B, That]): That - def flatMap[S, That](f: T => GenTraversableOnce[S])(implicit bf: CanBuildFrom[Repr, S, That]): That + /** Builds a new collection by applying a function to all elements of this $coll + * and concatenating the results. + * + * @param f the function to apply to each element. + * @tparam B the element type of the returned collection. + * @tparam That $thatinfo + * @param bf $bfinfo + * @return a new collection of type `That` resulting from applying the given collection-valued function + * `f` to each element of this $coll and concatenating the results. + * + * @usecase def flatMap[B](f: A => TraversableOnce[B]): $Coll[B] + * + * @return a new $coll resulting from applying the given collection-valued function + * `f` to each element of this $coll and concatenating the results. + */ + def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That - def ++[U >: T, That](that: GenTraversableOnce[U])(implicit bf: CanBuildFrom[Repr, U, That]): That + /** Concatenates this $coll with the elements of a traversable collection. + * + * @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`. + * + * @usecase def ++[B](that: TraversableOnce[B]): $Coll[B] + * + * @return a new $coll which contains all elements of this $coll + * followed by all elements of `that`. + */ + def ++[B >: A, That](that: GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That - def filter(pred: T => Boolean): Repr + /** Selects all elements of this $coll which satisfy a predicate. + * + * @param p the predicate used to test elements. + * @return a new $coll consisting of all elements of this $coll that satisfy the given + * predicate `p`. Their order may not be preserved. + */ + def filter(pred: A => Boolean): Repr - def filterNot(pred: T => Boolean): Repr + /** Selects all elements of this $coll which do not satisfy a predicate. + * + * @param p the predicate used to test elements. + * @return a new $coll consisting of all elements of this $coll that do not satisfy the given + * predicate `p`. Their order may not be preserved. + */ + def filterNot(pred: A => Boolean): Repr - def partition(pred: T => Boolean): (Repr, Repr) + /** Partitions this $coll in two ${coll}s according to a predicate. + * + * @param p the predicate on which to partition. + * @return a pair of ${coll}s: the first $coll consists of all elements that + * satisfy the predicate `p` and the second $coll consists of all elements + * that don't. The relative order of the elements in the resulting ${coll}s + * may not be preserved. + */ + def partition(pred: A => Boolean): (Repr, Repr) - def groupBy[K](f: T => K): GenMap[K, Repr] + /** Partitions this $coll into a map of ${coll}s according to some discriminator function. + * + * Note: this method is not re-implemented by views. This means + * when applied to a view it will always force the view and + * return a new $coll. + * + * @param f the discriminator function. + * @tparam K the type of keys returned by the discriminator function. + * @return A map from keys to ${coll}s such that the following invariant holds: + * {{{ + * (xs partition f)(k) = xs filter (x => f(x) == k) + * }}} + * That is, every key `k` is bound to a $coll of those elements `x` + * for which `f(x)` equals `k`. + * + */ + def groupBy[K](f: A => K): GenMap[K, Repr] + /** Selects first ''n'' elements. + * $orderDependent + * @param n Tt number of elements to take from this $coll. + * @return a $coll consisting only of the first `n` elements of this $coll, + * or else the whole $coll, if it has less than `n` elements. + */ def take(n: Int): Repr + /** Selects all elements except first ''n'' ones. + * $orderDependent + * @param n the number of elements to drop from this $coll. + * @return a $coll consisting of all elements of this $coll except the first `n` ones, or else the + * empty $coll, if this $coll has less than `n` elements. + */ def drop(n: Int): Repr + /** Selects an interval of elements. The returned collection is made up + * of all elements `x` which satisfy the invariant: + * {{{ + * from <= indexOf(x) < until + * }}} + * $orderDependent + * + * @param from the lowest index to include from this $coll. + * @param until the highest index to EXCLUDE from this $coll. + * @return a $coll containing the elements greater than or equal to + * index `from` extending up to (but not including) index `until` + * of this $coll. + */ def slice(unc_from: Int, unc_until: Int): Repr + /** Splits this $coll into two at a given position. + * Note: `c splitAt n` is equivalent to (but possibly more efficient than) + * `(c take n, c drop n)`. + * $orderDependent + * + * @param n the position at which to split. + * @return a pair of ${coll}s consisting of the first `n` + * elements of this $coll, and the other elements. + */ def splitAt(n: Int): (Repr, Repr) - def takeWhile(pred: T => Boolean): Repr - - def span(pred: T => Boolean): (Repr, Repr) + /** Takes longest prefix of elements that satisfy a predicate. + * $orderDependent + * @param p The predicate used to test elements. + * @return the longest prefix of this $coll whose elements all satisfy + * the predicate `p`. + */ + def takeWhile(pred: A => Boolean): Repr - def dropWhile(pred: T => Boolean): Repr + /** Splits this $coll into a prefix/suffix pair according to a predicate. + * + * Note: `c span p` is equivalent to (but possibly more efficient than) + * `(c takeWhile p, c dropWhile p)`, provided the evaluation of the + * predicate `p` does not cause any side-effects. + * $orderDependent + * + * @param p the test predicate + * @return a pair consisting of the longest prefix of this $coll whose + * elements all satisfy `p`, and the rest of this $coll. + */ + def span(pred: A => Boolean): (Repr, Repr) - def copyToArray[U >: T](xs: Array[U], start: Int, len: Int) + /** Drops longest prefix of elements that satisfy a predicate. + * $orderDependent + * @param p The predicate used to test elements. + * @return the longest suffix of this $coll whose first element + * does not satisfy the predicate `p`. + */ + def dropWhile(pred: A => Boolean): Repr + /** Defines the prefix of this object's `toString` representation. + * + * @return a string representation which starts the result of `toString` + * applied to this $coll. By default the string prefix is the + * simple name of the collection class $coll. + */ def stringPrefix: String } diff --git a/src/library/scala/collection/GenTraversableOnceLike.scala b/src/library/scala/collection/GenTraversableOnceLike.scala index dcc9ba805e..6431b334cf 100644 --- a/src/library/scala/collection/GenTraversableOnceLike.scala +++ b/src/library/scala/collection/GenTraversableOnceLike.scala @@ -20,21 +20,60 @@ package scala.collection * This trait may possibly have operations implemented in parallel. * @define undefinedorder * The order in which operations are performed on elements is unspecified and may be nondeterministic. + * @define orderDependent + * + * Note: might return different results for different runs, unless the underlying collection type is ordered. + * @define orderDependentFold + * + * Note: might return different results for different runs, unless the + * underlying collection type is ordered or the operator is associative + * and commutative. + * @define mayNotTerminateInf + * + * Note: may not terminate for infinite-sized collections. + * @define willNotTerminateInf + * + * Note: will not terminate for infinite-sized collections. * * @author Martin Odersky * @author Aleksandar Prokopec * @since 2.9 */ -trait GenTraversableOnceLike[+A] { +private[collection] trait GenTraversableOnceLike[+A] { def foreach[U](f: A => U): Unit - def isEmpty: Boolean - def hasDefiniteSize: Boolean def seq: TraversableOnce[A] + /** The size of this $coll. + * + * $willNotTerminateInf + * + * @return the number of elements in this $coll. + */ + def size: Int + + /** Tests whether the $coll is empty. + * + * @return `true` if the $coll contains no elements, `false` otherwise. + */ + def isEmpty: Boolean + + /** Tests whether the $coll is not empty. + * + * @return `true` if the $coll contains at least one element, `false` otherwise. + */ + def nonEmpty: Boolean + + /** Tests whether this $coll can be repeatedly traversed. Always + * true for Traversables and false for Iterators unless overridden. + * + * @return `true` if it is repeatedly traversable, `false` otherwise. + */ + def isTraversableAgain: Boolean + /** Reduces the elements of this sequence using the specified associative binary operator. * * $undefinedorder @@ -88,6 +127,81 @@ trait GenTraversableOnceLike[+A] { /** A syntactic sugar for out of order folding. See `fold`. */ 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, + * going left to right. + * + * Note: `/:` is alternate syntax for `foldLeft`; `z /: xs` is the same as + * `xs foldLeft z`. + * $willNotTerminateInf + * $orderDependentFold + * + * @param z the start value. + * @param op the binary operator. + * @tparam B the result type of the binary operator. + * @return the result of inserting `op` between consecutive elements of this $coll, + * going left to right with the start value `z` on the left: + * {{{ + * op(...op(op(z, x,,1,,), x,,2,,), ..., x,,n,,) + * }}} + * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. + */ + def /:[B](z: B)(op: (B, A) => B): B + + /** Applies a binary operator to all elements of this $coll and a start value, + * going right to left. + * + * Note: `:\` is alternate syntax for `foldRight`; `xs :\ z` is the same as + * `xs foldRight z`. + * $willNotTerminateInf + * $orderDependentFold + * + * @param z the start value + * @param op the binary operator + * @tparam B the result type of the binary operator. + * @return the result of inserting `op` between consecutive elements of this $coll, + * going right to left with the start value `z` on the right: + * {{{ + * op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...)) + * }}} + * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. + */ + def :\[B](z: B)(op: (A, B) => B): B + + /** Applies a binary operator to a start value and all elements of this $coll, + * going left to right. + * + * $willNotTerminateInf + * $orderDependentFold + * + * @param z the start value. + * @param op the binary operator. + * @tparam B the result type of the binary operator. + * @return the result of inserting `op` between consecutive elements of this $coll, + * going left to right with the start value `z` on the left: + * {{{ + * op(...op(z, x,,1,,), x,,2,,, ..., x,,n,,) + * }}} + * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. + */ + def foldLeft[B](z: B)(op: (B, A) => B): B + + /** Applies a binary operator to all elements of this $coll and a start value, + * going right to left. + * + * $willNotTerminateInf + * $orderDependentFold + * @param z the start value. + * @param op the binary operator. + * @tparam B the result type of the binary operator. + * @return the result of inserting `op` between consecutive elements of this $coll, + * going right to left with the start value `z` on the right: + * {{{ + * op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...)) + * }}} + * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. + */ + def foldRight[B](z: B)(op: (A, B) => B): B + /** Aggregates the results of applying an operator to subsequent elements. * * This is a more general form of `fold` and `reduce`. It has similar semantics, but does @@ -118,14 +232,105 @@ trait GenTraversableOnceLike[+A] { */ def aggregate[B](z: B)(seqop: (B, A) => B, combop: (B, B) => B): B + /** Applies a binary operator to all elements of this $coll, going right to left. + * $willNotTerminateInf + * $orderDependentFold + * + * @param op the binary operator. + * @tparam B the result type of the binary operator. + * @return the result of inserting `op` between consecutive elements of this $coll, + * going right to left: + * {{{ + * op(x,,1,,, op(x,,2,,, ..., op(x,,n-1,,, x,,n,,)...)) + * }}} + * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. + * @throws `UnsupportedOperationException` if this $coll is empty. + */ + def reduceRight[B >: A](op: (A, B) => B): B + + /** Optionally applies a binary operator to all elements of this $coll, going left to right. + * $willNotTerminateInf + * $orderDependentFold + * + * @param op the binary operator. + * @tparam B the result type of the binary operator. + * @return an option value containing the result of `reduceLeft(op)` is this $coll is nonempty, + * `None` otherwise. + */ + def reduceLeftOption[B >: A](op: (B, A) => B): Option[B] + + /** Optionally applies a binary operator to all elements of this $coll, going + * right to left. + * $willNotTerminateInf + * $orderDependentFold + * + * @param op the binary operator. + * @tparam B the result type of the binary operator. + * @return an option value containing the result of `reduceRight(op)` is this $coll is nonempty, + * `None` otherwise. + */ + def reduceRightOption[B >: A](op: (A, B) => B): Option[B] + + /** Counts the number of elements in the $coll which satisfy a predicate. + * + * @param p the predicate used to test elements. + * @return the number of elements satisfying the predicate `p`. + */ def count(p: A => Boolean): Int + /** Sums up the elements of this collection. + * + * @param num an implicit parameter defining a set of numeric operations + * which includes the `+` operator to be used in forming the sum. + * @tparam B the result type of the `+` operator. + * @return the sum of all elements of this $coll with respect to the `+` operator in `num`. + * + * @usecase def sum: A + * + * @return the sum of all elements in this $coll of numbers of type `Int`. + * Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation + * can be used as element type of the $coll and as result type of `sum`. + * Examples of such types are: `Long`, `Float`, `Double`, `BigInt`. + * + */ def sum[A1 >: A](implicit num: Numeric[A1]): A1 + /** Multiplies up the elements of this collection. + * + * @param num an implicit parameter defining a set of numeric operations + * which includes the `*` operator to be used in forming the product. + * @tparam B the result type of the `*` operator. + * @return the product of all elements of this $coll with respect to the `*` operator in `num`. + * + * @usecase def product: A + * + * @return the product of all elements in this $coll of numbers of type `Int`. + * Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation + * can be used as element type of the $coll and as result type of `product`. + * Examples of such types are: `Long`, `Float`, `Double`, `BigInt`. + */ def product[A1 >: A](implicit num: Numeric[A1]): A1 + /** Finds the smallest element. + * + * @param cmp An ordering to be used for comparing elements. + * @tparam B The type over which the ordering is defined. + * @return the smallest element of this $coll with respect to the ordering `cmp`. + * + * @usecase def min: A + * @return the smallest element of this $coll + */ def min[A1 >: A](implicit ord: Ordering[A1]): A + /** Finds the largest element. + * + * @param cmp An ordering to be used for comparing elements. + * @tparam B The type over which the ordering is defined. + * @return the largest element of this $coll with respect to the ordering `cmp`. + * + * @usecase def max: A + * @return the largest element of this $coll. + */ def max[A1 >: A](implicit ord: Ordering[A1]): A def maxBy[B](f: A => B)(implicit cmp: Ordering[B]): A @@ -136,39 +341,170 @@ trait GenTraversableOnceLike[+A] { def exists(pred: A => Boolean): Boolean + /** Finds the first element of the $coll satisfying a predicate, if any. + * + * $mayNotTerminateInf + * $orderDependent + * + * @param p the predicate used to test elements. + * @return an option value containing the first element in the $coll + * that satisfies `p`, or `None` if none exists. + */ def find(pred: A => Boolean): Option[A] + /** Copies values of this $coll to an array. + * Fills the given array `xs` with values of this $coll. + * Copying will stop once either the end of the current $coll is reached, + * or the end of the array is reached. + * + * $willNotTerminateInf + * + * @param xs the array to fill. + * @tparam B the type of the elements of the array. + * + * @usecase def copyToArray(xs: Array[A]): Unit + */ def copyToArray[B >: A](xs: Array[B]): Unit + /** Copies values of this $coll to an array. + * Fills the given array `xs` with values of this $coll, after skipping `start` values. + * Copying will stop once either the end of the current $coll is reached, + * or the end of the array is reached. + * + * $willNotTerminateInf + * + * @param xs the array to fill. + * @param start the starting index. + * @tparam B the type of the elements of the array. + * + * @usecase def copyToArray(xs: Array[A], start: Int): Unit + */ def copyToArray[B >: A](xs: Array[B], start: Int): Unit def copyToArray[B >: A](xs: Array[B], start: Int, len: Int): Unit + /** Displays all elements of this $coll in a string using start, end, and + * separator strings. + * + * @param start the starting string. + * @param sep the separator string. + * @param end the ending string. + * @return a string representation of this $coll. The resulting string + * begins with the string `start` and ends with the string + * `end`. Inside, the string representations (w.r.t. the method + * `toString`) of all elements of this $coll are separated by + * the string `sep`. + * + * @example `List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"` + */ def mkString(start: String, sep: String, end: String): String + /** Displays all elements of this $coll in a string using a separator string. + * + * @param sep the separator string. + * @return a string representation of this $coll. In the resulting string + * the string representations (w.r.t. the method `toString`) + * of all elements of this $coll are separated by the string `sep`. + * + * @example `List(1, 2, 3).mkString("|") = "1|2|3"` + */ def mkString(sep: String): String + /** Displays all elements of this $coll in a string. + * + * @return a string representation of this $coll. In the resulting string + * the string representations (w.r.t. the method `toString`) + * of all elements of this $coll follow each other without any + * separator string. + */ def mkString: String + /** Converts this $coll to an array. + * $willNotTerminateInf + * + * @tparam B the type of the elements of the array. A `ClassManifest` for + * this type must be available. + * @return an array containing all elements of this $coll. + * + * @usecase def toArray: Array[A] + * @return an array containing all elements of this $coll. + * A `ClassManifest` must be available for the element type of this $coll. + */ def toArray[A1 >: A: ClassManifest]: Array[A1] + /** Converts this $coll to a list. + * $willNotTerminateInf + * @return a list containing all elements of this $coll. + */ def toList: List[A] + /** Converts this $coll to an indexed sequence. + * $willNotTerminateInf + * @return an indexed sequence containing all elements of this $coll. + */ def toIndexedSeq[A1 >: A]: immutable.IndexedSeq[A1] + /** Converts this $coll to a stream. + * $willNotTerminateInf + * @return a stream containing all elements of this $coll. + */ def toStream: Stream[A] + /** Returns an Iterator over the elements in this $coll. Will return + * the same Iterator if this instance is already an Iterator. + * $willNotTerminateInf + * @return an Iterator containing all elements of this $coll. + */ def toIterator: Iterator[A] + /** Converts this $coll to a mutable buffer. + * $willNotTerminateInf + * @return a buffer containing all elements of this $coll. + */ def toBuffer[A1 >: A]: collection.mutable.Buffer[A1] + /** Converts this $coll to an unspecified Traversable. Will return + * the same collection if this instance is already Traversable. + * $willNotTerminateInf + * @return a Traversable containing all elements of this $coll. + */ def toTraversable: GenTraversable[A] + /** Converts this $coll to an iterable collection. Note that + * the choice of target `Iterable` is lazy in this default implementation + * as this `TraversableOnce` may be lazy and unevaluated (i.e. it may + * be an iterator which is only traversable once). + * + * $willNotTerminateInf + * @return an `Iterable` containing all elements of this $coll. + */ def toIterable: GenIterable[A] + /** Converts this $coll to a sequence. As with `toIterable`, it's lazy + * in this default implementation, as this `TraversableOnce` may be + * lazy and unevaluated. + * + * $willNotTerminateInf + * @return a sequence containing all elements of this $coll. + */ def toSeq: GenSeq[A] + /** Converts this $coll to a set. + * $willNotTerminateInf + * @return a set containing all elements of this $coll. + */ def toSet[A1 >: A]: GenSet[A1] + /** Converts this $coll to a map. This method is unavailable unless + * the elements are members of Tuple2, each ((T, U)) becoming a key-value + * pair in the map. Duplicate keys will be overwritten by later keys: + * if this is an unordered collection, which key is in the resulting map + * is undefined. + * $willNotTerminateInf + * @return a map containing all elements of this $coll. + * @usecase def toMap[T, U]: Map[T, U] + * @return a map of type `immutable.Map[T, U]` + * containing all key/value pairs of type `(T, U)` of this $coll. + */ def toMap[K, V](implicit ev: A <:< (K, V)): GenMap[K, V] } diff --git a/src/library/scala/collection/GenTraversableViewLike.scala b/src/library/scala/collection/GenTraversableViewLike.scala index 5332b06503..3d2ebf3a22 100644 --- a/src/library/scala/collection/GenTraversableViewLike.scala +++ b/src/library/scala/collection/GenTraversableViewLike.scala @@ -16,9 +16,9 @@ import annotation.migration -trait GenTraversableViewLike[+A, - +Coll, - +This <: GenTraversableView[A, Coll] with GenTraversableViewLike[A, Coll, This]] +private[collection] trait GenTraversableViewLike[+A, + +Coll, + +This <: GenTraversableView[A, Coll] with GenTraversableViewLike[A, Coll, This]] extends GenTraversable[A] with GenTraversableLike[A, This] { self => diff --git a/src/library/scala/collection/IterableLike.scala b/src/library/scala/collection/IterableLike.scala index 4d10f31920..fe87d1a6d9 100644 --- a/src/library/scala/collection/IterableLike.scala +++ b/src/library/scala/collection/IterableLike.scala @@ -8,10 +8,12 @@ package scala.collection + import generic._ import immutable.{ List, Stream } import annotation.unchecked.uncheckedVariance + /** A template trait for iterable collections of type `Iterable[A]`. * $iterableInfo * @define iterableInfo @@ -46,14 +48,6 @@ import annotation.unchecked.uncheckedVariance * * @define Coll Iterable * @define coll iterable collection - * @define zipthatinfo the class of the returned collection. Where possible, `That` is - * the same class as the current collection class `Repr`, but this - * depends on the element type `(A1, B)` being admissible for that class, - * which means that an implicit instance of type `CanBuildFrom[Repr, (A1, B), That]`. - * is found. - * @define zipbfinfo an implicit value of class `CanBuildFrom` which determines the - * result class `That` from the current representation type `Repr` - * and the new element type `(A1, B)`. */ trait IterableLike[+A, +Repr] extends Equals with TraversableLike[A, Repr] with GenIterableLike[A, Repr] { self => @@ -194,30 +188,6 @@ self => } } - /** Returns a $coll formed from this $coll and another iterable collection - * by combining corresponding elements in pairs. - * If one of the two collections is longer than the other, its remaining elements are ignored. - * - * $orderDependent - * - * @param that The iterable providing the second half of each result pair - * @tparam A1 the type of the first half of the returned pairs (this is always a supertype - * of the collection's element type `A`). - * @tparam B the type of the second half of the returned pairs - * @tparam That $zipthatinfo - * @param bf $zipbfinfo - * @return a new collection of type `That` containing pairs consisting of - * corresponding elements of this $coll and `that`. The length - * of the returned collection is the minimum of the lengths of this $coll and `that`. - * - * @usecase def zip[B](that: Iterable[B]): $Coll[(A, B)] - * - * @param that The iterable providing the second half of each result pair - * @tparam B the type of the second half of the returned pairs - * @return a new $coll containing pairs consisting of - * corresponding elements of this $coll and `that`. The length - * of the returned collection is the minimum of the lengths of this $coll and `that`. - */ def zip[A1 >: A, B, That](that: GenIterable[B])(implicit bf: CanBuildFrom[Repr, (A1, B), That]): That = { val b = bf(repr) val these = this.iterator @@ -227,34 +197,6 @@ self => b.result } - /** Returns a $coll formed from this $coll and another iterable collection - * by combining corresponding elements in pairs. - * If one of the two collections is shorter than the other, - * placeholder elements are used to extend the shorter collection to the length of the longer. - * - * $orderDependent - * - * @param that the iterable providing the second half of each result pair - * @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`. - * @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll. - * @return a new collection of type `That` containing pairs consisting of - * corresponding elements of this $coll and `that`. The length - * of the returned collection is the maximum of the lengths of this $coll and `that`. - * If this $coll is shorter than `that`, `thisElem` values are used to pad the result. - * If `that` is shorter than this $coll, `thatElem` values are used to pad the result. - * - * @usecase def zipAll[B](that: Iterable[B], thisElem: A, thatElem: B): $Coll[(A, B)] - * - * @param that The iterable providing the second half of each result pair - * @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`. - * @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll. - * @tparam B the type of the second half of the returned pairs - * @return a new $coll containing pairs consisting of - * corresponding elements of this $coll and `that`. The length - * of the returned collection is the maximum of the lengths of this $coll and `that`. - * If this $coll is shorter than `that`, `thisElem` values are used to pad the result. - * If `that` is shorter than this $coll, `thatElem` values are used to pad the result. - */ def zipAll[B, A1 >: A, That](that: GenIterable[B], thisElem: A1, thatElem: B)(implicit bf: CanBuildFrom[Repr, (A1, B), That]): That = { val b = bf(repr) val these = this.iterator @@ -268,31 +210,6 @@ self => b.result } - /** Zips this $coll with its indices. - * - * $orderDependent - * - * @tparam A1 the type of the first half of the returned pairs (this is always a supertype - * of the collection's element type `A`). - * @tparam That the class of the returned collection. Where possible, `That` is - * the same class as the current collection class `Repr`, but this - * depends on the element type `(A1, Int)` being admissible for that class, - * which means that an implicit instance of type `CanBuildFrom[Repr, (A1, Int), That]`. - * is found. - * @tparam bf an implicit value of class `CanBuildFrom` which determines the - * result class `That` from the current representation type `Repr` - * and the new element type `(A1, Int)`. - * @return A new collection of type `That` containing pairs consisting of all elements of this - * $coll paired with their index. Indices start at `0`. - * - * @usecase def zipWithIndex: $Coll[(A, Int)] - * - * @return A new $coll containing pairs consisting of all elements of this - * $coll paired with their index. Indices start at `0`. - * @example - * `List("a", "b", "c").zipWithIndex = List(("a", 0), ("b", 1), ("c", 2))` - * - */ def zipWithIndex[A1 >: A, That](implicit bf: CanBuildFrom[Repr, (A1, Int), That]): That = { val b = bf(repr) var i = 0 @@ -303,20 +220,6 @@ self => b.result } - /** Checks if the other iterable collection contains the same elements in the same order as this $coll. - * - * $orderDependent - * $willNotTerminateInf - * - * @param that the collection to compare with. - * @tparam B the type of the elements of collection `that`. - * @return `true`, if both collections contain the same elements in the same order, `false` otherwise. - * - * @usecase def sameElements(that: Iterable[A]): Boolean - * - * @param that the collection to compare with. - * @return `true`, if both collections contain the same elements in the same order, `false` otherwise. - */ def sameElements[B >: A](that: GenIterable[B]): Boolean = { val these = this.iterator val those = that.iterator diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala index 05f89dd098..b14c546acc 100644 --- a/src/library/scala/collection/SeqLike.scala +++ b/src/library/scala/collection/SeqLike.scala @@ -64,22 +64,8 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] override protected[this] def thisCollection: Seq[A] = this.asInstanceOf[Seq[A]] override protected[this] def toCollection(repr: Repr): Seq[A] = repr.asInstanceOf[Seq[A]] - /** The length of the $coll. - * - * $willNotTerminateInf - * - * Note: `xs.length` and `xs.size` yield the same result. - * - * @return the number of elements in this $coll. - */ def length: Int - /** Selects an element by its index in the $coll. - * - * @param idx The index to select. - * @return the element of this $coll at index `idx`, where `0` indicates the first element. - * @throws `IndexOutOfBoundsException` if `idx` does not satisfy `0 <= idx < length`. - */ def apply(idx: Int): A protected[this] override def parCombiner = ParSeq.newCombiner[A] @@ -113,25 +99,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] */ override def size = length - /** Tests whether this $coll contains given index. - * - * The implementations of methods `apply` and `isDefinedAt` turn a `Seq[A]` into - * a `PartialFunction[Int, A]`. - * - * @param idx the index to test - * @return `true` if this $coll contains an element at position `idx`, `false` otherwise. - */ - def isDefinedAt(idx: Int): Boolean = (idx >= 0) && (idx < length) - - /** Computes length of longest segment whose elements all satisfy some predicate. - * - * $mayNotTerminateInf - * - * @param p the predicate used to test elements. - * @param from the index where the search starts. - * @return the length of the longest segment of this $coll starting from index `from` - * such that every element of the segment satisfies the predicate `p`. - */ def segmentLength(p: A => Boolean, from: Int): Int = { var i = 0 var it = iterator.drop(from) @@ -140,35 +107,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] i } - /** Returns the length of the longest prefix whose elements all satisfy some predicate. - * - * $mayNotTerminateInf - * - * @param p the predicate used to test elements. - * @return the length of the longest prefix of this $coll - * such that every element of the segment satisfies the predicate `p`. - */ - def prefixLength(p: A => Boolean) = segmentLength(p, 0) - - /** Finds index of first element satisfying some predicate. - * - * $mayNotTerminateInf - * - * @param p the predicate used to test elements. - * @return the index of the first element of this $coll that satisfies the predicate `p`, - * or `-1`, if none exists. - */ - def indexWhere(p: A => Boolean): Int = indexWhere(p, 0) - - /** Finds index of the first element satisfying some predicate after or at some start index. - * - * $mayNotTerminateInf - * - * @param p the predicate used to test elements. - * @param from the start index - * @return the index `>= from` of the first element of this $coll that satisfies the predicate `p`, - * or `-1`, if none exists. - */ def indexWhere(p: A => Boolean, from: Int): Int = { var i = from var it = iterator.drop(from) @@ -185,74 +123,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] @deprecated("Use indexWhere(p) instead.") def findIndexOf(p: A => Boolean): Int = indexWhere(p) - /** Finds index of first occurrence of some value in this $coll. - * - * $mayNotTerminateInf - * - * @param elem the element value to search for. - * @tparam B the type of the element `elem`. - * @return the index of the first element of this $coll that is equal (wrt `==`) - * to `elem`, or `-1`, if none exists. - * - * @usecase def indexOf(elem: A): Int - */ - def indexOf[B >: A](elem: B): Int = indexOf(elem, 0) - - /** Finds index of first occurrence of some value in this $coll after or at some start index. - * - * $mayNotTerminateInf - * - * @param elem the element value to search for. - * @tparam B the type of the element `elem`. - * @param from the start index - * @return the index `>= from` of the first element of this $coll that is equal (wrt `==`) - * to `elem`, or `-1`, if none exists. - * - * @usecase def indexOf(elem: A, from: Int): Int - */ - def indexOf[B >: A](elem: B, from: Int): Int = indexWhere(elem ==, from) - - /** Finds index of last occurrence of some value in this $coll. - * - * $willNotTerminateInf - * - * @param elem the element value to search for. - * @tparam B the type of the element `elem`. - * @return the index of the last element of this $coll that is equal (wrt `==`) - * to `elem`, or `-1`, if none exists. - * - * @usecase def lastIndexOf(elem: A): Int - */ - def lastIndexOf[B >: A](elem: B): Int = lastIndexWhere(elem ==) - - /** Finds index of last occurrence of some value in this $coll before or at a given end index. - * - * @param elem the element value to search for. - * @param end the end index. - * @tparam B the type of the element `elem`. - * @return the index `<= end` of the last element of this $coll that is equal (wrt `==`) - * to `elem`, or `-1`, if none exists. - * - * @usecase def lastIndexOf(elem: A, end: Int): Int - */ - def lastIndexOf[B >: A](elem: B, end: Int): Int = lastIndexWhere(elem ==, end) - - /** Finds index of last element satisfying some predicate. - * - * $willNotTerminateInf - * - * @param p the predicate used to test elements. - * @return the index of the last element of this $coll that satisfies the predicate `p`, - * or `-1`, if none exists. - */ - def lastIndexWhere(p: A => Boolean): Int = lastIndexWhere(p, length - 1) - - /** Finds index of last element satisfying some predicate before or at given end index. - * - * @param p the predicate used to test elements. - * @return the index `<= end` of the last element of this $coll that satisfies the predicate `p`, - * or `-1`, if none exists. - */ def lastIndexWhere(p: A => Boolean, end: Int): Int = { var i = length - 1 val it = reverseIterator @@ -388,12 +258,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] } } - /** Returns new $coll wih elements in reversed order. - * - * $willNotTerminateInf - * - * @return A new $coll with all elements of this $coll in reversed order. - */ def reverse: Repr = { var xs: List[A] = List() for (x <- this) @@ -405,27 +269,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] b.result } - /** - * Builds a new collection by applying a function to all elements of this $coll and - * collecting the results in reversed order. - * - * $willNotTerminateInf - * - * Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient. - * - * @param f the function to apply to each element. - * @tparam B the element type of the returned collection. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new collection of type `That` resulting from applying the given function - * `f` to each element of this $coll and collecting the results in reversed order. - * - * @usecase def reverseMap[B](f: A => B): $Coll[B] - * - * Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient. - * @return a new $coll resulting from applying the given function - * `f` to each element of this $coll and collecting the results in reversed order. - */ def reverseMap[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That = { var xs: List[A] = List() for (x <- this.seq) @@ -450,17 +293,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] @deprecated("use `reverseIterator' instead") def reversedElements = reverseIterator - /** Tests whether this $coll contains the given sequence at a given index. - * - * If the both the receiver object, <code>this</code> and - * the argument, <code>that</code> are infinite sequences - * this method may not terminate. - * - * @param that the sequence to test - * @param offset the index where the sequence is searched. - * @return `true` if the sequence `that` is contained in this $coll at index `offset`, - * otherwise `false`. - */ def startsWith[B](that: GenSeq[B], offset: Int): Boolean = { val i = this.iterator drop offset val j = that.iterator @@ -471,18 +303,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] !j.hasNext } - /** Tests whether this $coll starts with the given sequence. - * - * @param that the sequence to test - * @return `true` if this collection has `that` as a prefix, `false` otherwise. - */ - def startsWith[B](that: GenSeq[B]): Boolean = startsWith(that, 0) - - /** Tests whether this $coll ends with the given sequence. - * $willNotTerminateInf - * @param that the sequence to test - * @return `true` if this $coll has `that` as a suffix, `false` otherwise. - */ def endsWith[B](that: GenSeq[B]): Boolean = { val i = this.iterator.drop(length - that.length) val j = that.iterator @@ -662,22 +482,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] b.result } - /** Produces a new $coll where a slice of elements in this $coll is replaced by another sequence. - * - * @param from the index of the first replaced element - * @param patch the replacement sequence - * @param replaced the number of elements to drop in the original $coll - * @tparam B the element type of the returned $coll. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new $coll consisting of all elements of this $coll - * except that `replaced` elements starting from `from` are replaced - * by `patch`. - * @usecase def patch(from: Int, that: Seq[A], replaced: Int): $Coll[A] - * @return a new $coll consisting of all elements of this $coll - * except that `replaced` elements starting from `from` are replaced - * by `patch`. - */ def patch[B >: A, That](from: Int, patch: GenSeq[B], replaced: Int)(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) val (prefix, rest) = this.splitAt(from) @@ -687,16 +491,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] b.result } - /** A copy of this $coll with one single replaced element. - * @param index the position of the replacement - * @param elem the replacing element - * @tparam B the element type of the returned $coll. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new $coll` which is a copy of this $coll with the element at position `index` replaced by `elem`. - * @usecase def updated(index: Int, elem: A): $Coll[A] - * @return a copy of this $coll with the element at position `index` replaced by `elem`. - */ def updated[B >: A, That](index: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) val (prefix, rest) = this.splitAt(index) @@ -706,17 +500,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] b.result } - /** Prepends an element to this $coll - * @param elem the prepended element - * @tparam B the element type of the returned $coll. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new collection of type `That` consisting of `elem` followed - * by all elements of this $coll. - * @usecase def +:(elem: A): $Coll[A] - * @return a new $coll consisting of `elem` followed - * by all elements of this $coll. - */ def +:[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) b += elem @@ -724,18 +507,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] b.result } - /** Appends an element to this $coll - * $willNotTerminateInf - * @param elem the appended element - * @tparam B the element type of the returned $coll. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new collection of type `That` consisting of - * all elements of this $coll followed by `elem`. - * @usecase def :+(elem: A): $Coll[A] - * @return a new $coll consisting of - * all elements of this $coll followed by `elem`. - */ def :+[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) b ++= thisCollection @@ -743,20 +514,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] b.result } - /** Appends an element value to this $coll 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. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new collection of type `That` consisting of - * all elements of this $coll followed by the minimal number of occurrences of `elem` so - * that the resulting collection has a length of at least `len`. - * @usecase def padTo(len: Int, elem: A): $Coll[A] - * @return a new $coll consisting of - * all elements of this $coll followed by the minimal number of occurrences of `elem` so - * that the resulting $coll has a length of at least `len`. - */ def padTo[B >: A, That](len: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) b.sizeHint(length max len) @@ -769,16 +526,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] b.result } - /** Tests whether every element of this $coll relates to the - * corresponding element of another sequence by satisfying a test predicate. - * - * @param that the other sequence - * @param p the test predicate, which relates elements from both sequences - * @tparam B the type of the elements of `that` - * @return `true` if both sequences have the same length and - * `p(x, y)` is `true` for all corresponding elements `x` of this $coll - * and `y` of `that`, otherwise `false`. - */ def corresponds[B](that: GenSeq[B])(p: (A,B) => Boolean): Boolean = { val i = this.iterator val j = that.iterator diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala index 5dc38e2043..bffd46a72c 100644 --- a/src/library/scala/collection/TraversableLike.scala +++ b/src/library/scala/collection/TraversableLike.scala @@ -134,11 +134,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] result } - /** Tests whether this $coll can be repeatedly traversed. - * @return `true` - */ - final def isTraversableAgain = true - /** Tests whether this $coll is known to have a finite size. * All strict collections are known to have finite size. For a non-strict collection * such as `Stream`, the predicate returns `true` if all elements have been computed. @@ -150,20 +145,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] */ def hasDefiniteSize = true - /** Concatenates this $coll with the elements of a traversable collection. - * - * @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`. - * - * @usecase def ++[B](that: TraversableOnce[B]): $Coll[B] - * - * @return a new $coll which contains all elements of this $coll - * followed by all elements of `that`. - */ def ++[B >: A, That](that: GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) if (that.isInstanceOf[IndexedSeqLike[_, _]]) b.sizeHint(this, that.seq.size) @@ -204,20 +185,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] def ++:[B >: A, That](that: Traversable[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = (that ++ seq)(breakOut) - /** Builds a new collection by applying a function to all elements of this $coll. - * - * @param f the function to apply to each element. - * @tparam B the element type of the returned collection. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new collection of type `That` resulting from applying the given function - * `f` to each element of this $coll and collecting the results. - * - * @usecase def map[B](f: A => B): $Coll[B] - * - * @return a new $coll resulting from applying the given function - * `f` to each element of this $coll and collecting the results. - */ def map[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) b.sizeHint(this) @@ -225,21 +192,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] b.result } - /** Builds a new collection by applying a function to all elements of this $coll - * and concatenating the results. - * - * @param f the function to apply to each element. - * @tparam B the element type of the returned collection. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new collection of type `That` resulting from applying the given collection-valued function - * `f` to each element of this $coll and concatenating the results. - * - * @usecase def flatMap[B](f: A => TraversableOnce[B]): $Coll[B] - * - * @return a new $coll resulting from applying the given collection-valued function - * `f` to each element of this $coll and concatenating the results. - */ def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) for (x <- this) b ++= f(x).seq @@ -267,23 +219,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] */ def filterNot(p: A => Boolean): Repr = filter(!p(_)) - /** Builds a new collection by applying a partial function to all elements of this $coll - * on which the function is defined. - * - * @param pf the partial function which filters and maps the $coll. - * @tparam B the element type of the returned collection. - * @tparam That $thatinfo - * @param bf $bfinfo - * @return a new collection of type `That` resulting from applying the partial function - * `pf` to each element on which it is defined and collecting the results. - * The order of the elements is preserved. - * - * @usecase def collect[B](pf: PartialFunction[A, B]): $Coll[B] - * - * @return a new $coll resulting from applying the given partial function - * `pf` to each element on which it is defined and collecting the results. - * The order of the elements is preserved. - */ def collect[B, That](pf: PartialFunction[A, B])(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) for (x <- this) if (pf.isDefinedAt(x)) b += pf(x) @@ -332,22 +267,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] (l.result, r.result) } - /** Partitions this $coll into a map of ${coll}s according to some discriminator function. - * - * Note: this method is not re-implemented by views. This means - * when applied to a view it will always force the view and - * return a new $coll. - * - * @param f the discriminator function. - * @tparam K the type of keys returned by the discriminator function. - * @return A map from keys to ${coll}s such that the following invariant holds: - * {{{ - * (xs partition f)(k) = xs filter (x => f(x) == k) - * }}} - * That is, every key `k` is bound to a $coll of those elements `x` - * for which `f(x)` equals `k`. - * - */ def groupBy[K](f: A => K): immutable.Map[K, Repr] = { val m = mutable.Map.empty[K, Builder[A, Repr]] for (elem <- this) { @@ -416,19 +335,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] def scan[B >: A, That](z: B)(op: (B, B) => B)(implicit cbf: CanBuildFrom[Repr, B, That]): That = scanLeft(z)(op) - /** Produces a collection containing cummulative results of applying the - * operator going left to right. - * - * $willNotTerminateInf - * $orderDependent - * - * @tparam B the type of the elements in the resulting collection - * @tparam That the actual type of the resulting collection - * @param z the initial value - * @param op the binary operator applied to the intermediate result and the element - * @param bf $bfinfo - * @return collection with intermediate results - */ def scanLeft[B, That](z: B)(op: (B, A) => B)(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) b.sizeHint(this, 1) @@ -438,23 +344,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] b.result } - /** Produces a collection containing cummulative results of applying the operator going right to left. - * The head of the collection is the last cummulative result. - * $willNotTerminateInf - * $orderDependent - * - * Example: - * {{{ - * List(1, 2, 3, 4).scanRight(0)(_ + _) == List(10, 9, 7, 4, 0) - * }}} - * - * @tparam B the type of the elements in the resulting collection - * @tparam That the actual type of the resulting collection - * @param z the initial value - * @param op the binary operator applied to the intermediate result and the element - * @param bf $bfinfo - * @return collection with intermediate results - */ @migration(2, 9, "This scanRight definition has changed in 2.9.\n" + "The previous behavior can be reproduced with scanRight.reverse." @@ -542,37 +431,12 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] b.result } - /** Selects first ''n'' elements. - * $orderDependent - * @param n Tt number of elements to take from this $coll. - * @return a $coll consisting only of the first `n` elements of this $coll, - * or else the whole $coll, if it has less than `n` elements. - */ def take(n: Int): Repr = slice(0, n) - /** Selects all elements except first ''n'' ones. - * $orderDependent - * @param n the number of elements to drop from this $coll. - * @return a $coll consisting of all elements of this $coll except the first `n` ones, or else the - * empty $coll, if this $coll has less than `n` elements. - */ def drop(n: Int): Repr = if (n <= 0) newBuilder ++= thisCollection result else sliceWithKnownDelta(n, Int.MaxValue, -n) - /** Selects an interval of elements. The returned collection is made up - * of all elements `x` which satisfy the invariant: - * {{{ - * from <= indexOf(x) < until - * }}} - * $orderDependent - * - * @param from the lowest index to include from this $coll. - * @param until the highest index to EXCLUDE from this $coll. - * @return a $coll containing the elements greater than or equal to - * index `from` extending up to (but not including) index `until` - * of this $coll. - */ def slice(from: Int, until: Int): Repr = sliceWithKnownBound(from max 0, until) // Precondition: from >= 0, until > 0, builder already configured for building. @@ -606,12 +470,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] } } - /** Takes longest prefix of elements that satisfy a predicate. - * $orderDependent - * @param p The predicate used to test elements. - * @return the longest prefix of this $coll whose elements all satisfy - * the predicate `p`. - */ def takeWhile(p: A => Boolean): Repr = { val b = newBuilder breakable { @@ -623,12 +481,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] b.result } - /** Drops longest prefix of elements that satisfy a predicate. - * $orderDependent - * @param p The predicate used to test elements. - * @return the longest suffix of this $coll whose first element - * does not satisfy the predicate `p`. - */ def dropWhile(p: A => Boolean): Repr = { val b = newBuilder var go = false @@ -639,17 +491,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] b.result } - /** Splits this $coll into a prefix/suffix pair according to a predicate. - * - * Note: `c span p` is equivalent to (but possibly more efficient than) - * `(c takeWhile p, c dropWhile p)`, provided the evaluation of the - * predicate `p` does not cause any side-effects. - * $orderDependent - * - * @param p the test predicate - * @return a pair consisting of the longest prefix of this $coll whose - * elements all satisfy `p`, and the rest of this $coll. - */ def span(p: A => Boolean): (Repr, Repr) = { val l, r = newBuilder var toLeft = true @@ -660,15 +501,6 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] (l.result, r.result) } - /** Splits this $coll into two at a given position. - * Note: `c splitAt n` is equivalent to (but possibly more efficient than) - * `(c take n, c drop n)`. - * $orderDependent - * - * @param n the position at which to split. - * @return a pair of ${coll}s consisting of the first `n` - * elements of this $coll, and the other elements. - */ def splitAt(n: Int): (Repr, Repr) = { val l, r = newBuilder l.sizeHintBounded(n, this) diff --git a/src/library/scala/collection/TraversableOnceLike.scala b/src/library/scala/collection/TraversableOnceLike.scala index c72156554a..462265f14a 100644 --- a/src/library/scala/collection/TraversableOnceLike.scala +++ b/src/library/scala/collection/TraversableOnceLike.scala @@ -37,20 +37,6 @@ import annotation.unchecked.{ uncheckedVariance => uV } * @since 2.9 * * @define coll traversable or iterator - * @define orderDependent - * - * Note: might return different results for different runs, unless the underlying collection type is ordered. - * @define orderDependentFold - * - * Note: might return different results for different runs, unless the - * underlying collection type is ordered or the operator is associative - * and commutative. - * @define mayNotTerminateInf - * - * Note: may not terminate for infinite-sized collections. - * @define willNotTerminateInf - * - * Note: will not terminate for infinite-sized collections. */ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { self => @@ -60,33 +46,6 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { def isEmpty: Boolean def hasDefiniteSize: Boolean - /** Tests whether this $coll can be repeatedly traversed. Always - * true for Traversables and false for Iterators unless overridden. - * - * @return `true` if it is repeatedly traversable, `false` otherwise. - */ - def isTraversableAgain: Boolean - - /** Returns an Iterator over the elements in this $coll. Will return - * the same Iterator if this instance is already an Iterator. - * $willNotTerminateInf - * @return an Iterator containing all elements of this $coll. - */ - def toIterator: Iterator[A] - - /** Converts this $coll to an unspecified Traversable. Will return - * the same collection if this instance is already Traversable. - * $willNotTerminateInf - * @return a Traversable containing all elements of this $coll. - */ - def toTraversable: Traversable[A] - - /** Converts this $coll to a stream. - * $willNotTerminateInf - * @return a stream containing all elements of this $coll. - */ - def toStream: Stream[A] - // Note: We could redefine this in TraversableLike to always return `repr` // of type `Repr`, only if `Repr` had type bounds, which it doesn't, because // not all `Repr` are a subtype `TraversableOnce[A]`. @@ -122,29 +81,14 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { elems } - /** The size of this $coll. - * - * $willNotTerminateInf - * - * @return the number of elements in this $coll. - */ def size: Int = { var result = 0 for (x <- self) result += 1 result } - /** Tests whether the $coll is not empty. - * - * @return `true` if the $coll contains at least one element, `false` otherwise. - */ def nonEmpty: Boolean = !isEmpty - /** Counts the number of elements in the $coll which satisfy a predicate. - * - * @param p the predicate used to test elements. - * @return the number of elements satisfying the predicate `p`. - */ def count(p: A => Boolean): Int = { var cnt = 0 for (x <- this) @@ -172,100 +116,19 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { None } - /** Applies a binary operator to a start value and all elements of this $coll, - * going left to right. - * - * Note: `/:` is alternate syntax for `foldLeft`; `z /: xs` is the same as - * `xs foldLeft z`. - * $willNotTerminateInf - * $orderDependentFold - * - * @param z the start value. - * @param op the binary operator. - * @tparam B the result type of the binary operator. - * @return the result of inserting `op` between consecutive elements of this $coll, - * going left to right with the start value `z` on the left: - * {{{ - * op(...op(op(z, x,,1,,), x,,2,,), ..., x,,n,,) - * }}} - * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. - */ def /:[B](z: B)(op: (B, A) => B): B = foldLeft(z)(op) - /** Applies a binary operator to all elements of this $coll and a start value, - * going right to left. - * - * Note: `:\` is alternate syntax for `foldRight`; `xs :\ z` is the same as - * `xs foldRight z`. - * $willNotTerminateInf - * $orderDependentFold - * - * @param z the start value - * @param op the binary operator - * @tparam B the result type of the binary operator. - * @return the result of inserting `op` between consecutive elements of this $coll, - * going right to left with the start value `z` on the right: - * {{{ - * op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...)) - * }}} - * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. - */ def :\[B](z: B)(op: (A, B) => B): B = foldRight(z)(op) - /** Applies a binary operator to a start value and all elements of this $coll, - * going left to right. - * - * $willNotTerminateInf - * $orderDependentFold - * - * @param z the start value. - * @param op the binary operator. - * @tparam B the result type of the binary operator. - * @return the result of inserting `op` between consecutive elements of this $coll, - * going left to right with the start value `z` on the left: - * {{{ - * op(...op(z, x,,1,,), x,,2,,, ..., x,,n,,) - * }}} - * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. - */ def foldLeft[B](z: B)(op: (B, A) => B): B = { var result = z this.seq foreach (x => result = op(result, x)) result } - /** Applies a binary operator to all elements of this $coll and a start value, - * going right to left. - * - * $willNotTerminateInf - * $orderDependentFold - * @param z the start value. - * @param op the binary operator. - * @tparam B the result type of the binary operator. - * @return the result of inserting `op` between consecutive elements of this $coll, - * going right to left with the start value `z` on the right: - * {{{ - * op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...)) - * }}} - * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. - */ def foldRight[B](z: B)(op: (A, B) => B): B = reversed.foldLeft(z)((x, y) => op(y, x)) - /** Applies a binary operator to all elements of this $coll, going left to right. - * $willNotTerminateInf - * $orderDependentFold - * - * @param op the binary operator. - * @tparam B the result type of the binary operator. - * @return the result of inserting `op` between consecutive elements of this $coll, - * going left to right: - * {{{ - * op(...(op(x,,1,,, x,,2,,), ... ) , x,,n,,) - * }}} - * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. - * @throws `UnsupportedOperationException` if this $coll is empty. - */ def reduceLeft[B >: A](op: (B, A) => B): B = { if (isEmpty) throw new UnsupportedOperationException("empty.reduceLeft") @@ -283,20 +146,6 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { acc } - /** Applies a binary operator to all elements of this $coll, going right to left. - * $willNotTerminateInf - * $orderDependentFold - * - * @param op the binary operator. - * @tparam B the result type of the binary operator. - * @return the result of inserting `op` between consecutive elements of this $coll, - * going right to left: - * {{{ - * op(x,,1,,, op(x,,2,,, ..., op(x,,n-1,,, x,,n,,)...)) - * }}} - * where `x,,1,,, ..., x,,n,,` are the elements of this $coll. - * @throws `UnsupportedOperationException` if this $coll is empty. - */ def reduceRight[B >: A](op: (A, B) => B): B = { if (isEmpty) throw new UnsupportedOperationException("empty.reduceRight") @@ -304,28 +153,9 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { reversed.reduceLeft[B]((x, y) => op(y, x)) } - /** Optionally applies a binary operator to all elements of this $coll, going left to right. - * $willNotTerminateInf - * $orderDependentFold - * - * @param op the binary operator. - * @tparam B the result type of the binary operator. - * @return an option value containing the result of `reduceLeft(op)` is this $coll is nonempty, - * `None` otherwise. - */ def reduceLeftOption[B >: A](op: (B, A) => B): Option[B] = if (isEmpty) None else Some(reduceLeft(op)) - /** Optionally applies a binary operator to all elements of this $coll, going - * right to left. - * $willNotTerminateInf - * $orderDependentFold - * - * @param op the binary operator. - * @tparam B the result type of the binary operator. - * @return an option value containing the result of `reduceRight(op)` is this $coll is nonempty, - * `None` otherwise. - */ def reduceRightOption[B >: A](op: (A, B) => B): Option[B] = if (isEmpty) None else Some(reduceRight(op)) @@ -337,48 +167,10 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { def aggregate[B](z: B)(seqop: (B, A) => B, combop: (B, B) => B): B = foldLeft(z)(seqop) - /** Sums up the elements of this collection. - * - * @param num an implicit parameter defining a set of numeric operations - * which includes the `+` operator to be used in forming the sum. - * @tparam B the result type of the `+` operator. - * @return the sum of all elements of this $coll with respect to the `+` operator in `num`. - * - * @usecase def sum: A - * - * @return the sum of all elements in this $coll of numbers of type `Int`. - * Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation - * can be used as element type of the $coll and as result type of `sum`. - * Examples of such types are: `Long`, `Float`, `Double`, `BigInt`. - * - */ def sum[B >: A](implicit num: Numeric[B]): B = foldLeft(num.zero)(num.plus) - /** Multiplies up the elements of this collection. - * - * @param num an implicit parameter defining a set of numeric operations - * which includes the `*` operator to be used in forming the product. - * @tparam B the result type of the `*` operator. - * @return the product of all elements of this $coll with respect to the `*` operator in `num`. - * - * @usecase def product: A - * - * @return the product of all elements in this $coll of numbers of type `Int`. - * Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation - * can be used as element type of the $coll and as result type of `product`. - * Examples of such types are: `Long`, `Float`, `Double`, `BigInt`. - */ def product[B >: A](implicit num: Numeric[B]): B = foldLeft(num.one)(num.times) - /** Finds the smallest element. - * - * @param cmp An ordering to be used for comparing elements. - * @tparam B The type over which the ordering is defined. - * @return the smallest element of this $coll with respect to the ordering `cmp`. - * - * @usecase def min: A - * @return the smallest element of this $coll - */ def min[B >: A](implicit cmp: Ordering[B]): A = { if (isEmpty) throw new UnsupportedOperationException("empty.min") @@ -386,15 +178,6 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { reduceLeft((x, y) => if (cmp.lteq(x, y)) x else y) } - /** Finds the largest element. - * - * @param cmp An ordering to be used for comparing elements. - * @tparam B The type over which the ordering is defined. - * @return the largest element of this $coll with respect to the ordering `cmp`. - * - * @usecase def max: A - * @return the largest element of this $coll. - */ def max[B >: A](implicit cmp: Ordering[B]): A = { if (isEmpty) throw new UnsupportedOperationException("empty.max") @@ -421,48 +204,12 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { */ def copyToBuffer[B >: A](dest: Buffer[B]): Unit = dest ++= seq - /** Copies values of this $coll to an array. - * Fills the given array `xs` with values of this $coll, after skipping `start` values. - * Copying will stop once either the end of the current $coll is reached, - * or the end of the array is reached. - * - * $willNotTerminateInf - * - * @param xs the array to fill. - * @param start the starting index. - * @tparam B the type of the elements of the array. - * - * @usecase def copyToArray(xs: Array[A], start: Int): Unit - */ def copyToArray[B >: A](xs: Array[B], start: Int): Unit = copyToArray(xs, start, xs.length - start) - /** Copies values of this $coll to an array. - * Fills the given array `xs` with values of this $coll. - * Copying will stop once either the end of the current $coll is reached, - * or the end of the array is reached. - * - * $willNotTerminateInf - * - * @param xs the array to fill. - * @tparam B the type of the elements of the array. - * - * @usecase def copyToArray(xs: Array[A]): Unit - */ def copyToArray[B >: A](xs: Array[B]): Unit = copyToArray(xs, 0, xs.length) - /** Converts this $coll to an array. - * $willNotTerminateInf - * - * @tparam B the type of the elements of the array. A `ClassManifest` for - * this type must be available. - * @return an array containing all elements of this $coll. - * - * @usecase def toArray: Array[A] - * @return an array containing all elements of this $coll. - * A `ClassManifest` must be available for the element type of this $coll. - */ def toArray[B >: A : ClassManifest]: Array[B] = { if (isTraversableAgain) { val result = new Array[B](size) @@ -472,60 +219,20 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { else toBuffer.toArray } - /** Converts this $coll to a list. - * $willNotTerminateInf - * @return a list containing all elements of this $coll. - */ + def toTraversable: Traversable[A] + def toList: List[A] = new ListBuffer[A] ++= seq toList - /** Converts this $coll to an iterable collection. Note that - * the choice of target `Iterable` is lazy in this default implementation - * as this `TraversableOnce` may be lazy and unevaluated (i.e. it may - * be an iterator which is only traversable once). - * - * $willNotTerminateInf - * @return an `Iterable` containing all elements of this $coll. - */ def toIterable: Iterable[A] = toStream - /** Converts this $coll to a sequence. As with `toIterable`, it's lazy - * in this default implementation, as this `TraversableOnce` may be - * lazy and unevaluated. - * - * $willNotTerminateInf - * @return a sequence containing all elements of this $coll. - */ def toSeq: Seq[A] = toStream - /** Converts this $coll to an indexed sequence. - * $willNotTerminateInf - * @return an indexed sequence containing all elements of this $coll. - */ def toIndexedSeq[B >: A]: immutable.IndexedSeq[B] = immutable.IndexedSeq() ++ seq - /** Converts this $coll to a mutable buffer. - * $willNotTerminateInf - * @return a buffer containing all elements of this $coll. - */ def toBuffer[B >: A]: mutable.Buffer[B] = new ArrayBuffer[B] ++= seq - /** Converts this $coll to a set. - * $willNotTerminateInf - * @return a set containing all elements of this $coll. - */ def toSet[B >: A]: immutable.Set[B] = immutable.Set() ++ seq - /** Converts this $coll to a map. This method is unavailable unless - * the elements are members of Tuple2, each ((T, U)) becoming a key-value - * pair in the map. Duplicate keys will be overwritten by later keys: - * if this is an unordered collection, which key is in the resulting map - * is undefined. - * $willNotTerminateInf - * @return a map containing all elements of this $coll. - * @usecase def toMap[T, U]: Map[T, U] - * @return a map of type `immutable.Map[T, U]` - * containing all key/value pairs of type `(T, U)` of this $coll. - */ def toMap[T, U](implicit ev: A <:< (T, U)): immutable.Map[T, U] = { val b = immutable.Map.newBuilder[T, U] for (x <- self) @@ -534,41 +241,11 @@ trait TraversableOnceLike[+A] extends GenTraversableOnceLike[A] { b.result } - /** Displays all elements of this $coll in a string using start, end, and - * separator strings. - * - * @param start the starting string. - * @param sep the separator string. - * @param end the ending string. - * @return a string representation of this $coll. The resulting string - * begins with the string `start` and ends with the string - * `end`. Inside, the string representations (w.r.t. the method - * `toString`) of all elements of this $coll are separated by - * the string `sep`. - * - * @example `List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"` - */ def mkString(start: String, sep: String, end: String): String = addString(new StringBuilder(), start, sep, end).toString - /** Displays all elements of this $coll in a string using a separator string. - * - * @param sep the separator string. - * @return a string representation of this $coll. In the resulting string - * the string representations (w.r.t. the method `toString`) - * of all elements of this $coll are separated by the string `sep`. - * - * @example `List(1, 2, 3).mkString("|") = "1|2|3"` - */ def mkString(sep: String): String = mkString("", sep, "") - /** Displays all elements of this $coll in a string. - * - * @return a string representation of this $coll. In the resulting string - * the string representations (w.r.t. the method `toString`) - * of all elements of this $coll follow each other without any - * separator string. - */ def mkString: String = mkString("") /** Appends all elements of this $coll to a string builder using start, end, diff --git a/src/library/scala/collection/mutable/ArraySeq.scala b/src/library/scala/collection/mutable/ArraySeq.scala index b6cafbb677..4b0b4779e9 100644 --- a/src/library/scala/collection/mutable/ArraySeq.scala +++ b/src/library/scala/collection/mutable/ArraySeq.scala @@ -52,7 +52,7 @@ extends IndexedSeq[A] val array: Array[AnyRef] = new Array[AnyRef](length) - override def par = ParArray.handoff(array.asInstanceOf[Array[A]]) + override def par = ParArray.handoff(array.asInstanceOf[Array[A]], length) def apply(idx: Int): A = { if (idx >= length) throw new IndexOutOfBoundsException(idx.toString) diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala index 51d487b773..b32ea108f4 100644 --- a/src/library/scala/collection/parallel/ParIterableLike.scala +++ b/src/library/scala/collection/parallel/ParIterableLike.scala @@ -210,6 +210,8 @@ self: ParIterableLike[T, Repr, Sequential] => def hasDefiniteSize = true + def nonEmpty = size != 0 + /** Creates a new parallel iterator used to traverse the elements of this parallel collection. * This iterator is more specific than the iterator of the returned by `iterator`, and augmented * with additional accessor and transformer methods. @@ -428,6 +430,22 @@ self: ParIterableLike[T, Repr, Sequential] => executeAndWaitResult(new Aggregate(z, seqop, combop, splitter)) } + def /:[S](z: S)(op: (S, T) => S): S = foldLeft(z)(op) + + def :\[S](z: S)(op: (T, S) => S): S = foldRight(z)(op) + + def foldLeft[S](z: S)(op: (S, T) => S): S = seq.foldLeft(z)(op) + + def foldRight[S](z: S)(op: (T, S) => S): S = seq.foldRight(z)(op) + + def reduceLeft[U >: T](op: (U, T) => U): U = seq.reduceLeft(op) + + def reduceRight[U >: T](op: (T, U) => U): U = seq.reduceRight(op) + + def reduceLeftOption[U >: T](op: (U, T) => U): Option[U] = seq.reduceLeftOption(op) + + def reduceRightOption[U >: T](op: (T, U) => U): Option[U] = seq.reduceRightOption(op) + /* /** Applies a function `f` to all the elements of $coll. Does so in a nondefined order, * and in parallel. diff --git a/src/library/scala/collection/parallel/ParSeqLike.scala b/src/library/scala/collection/parallel/ParSeqLike.scala index ba4a09d062..c9e6b45bd6 100644 --- a/src/library/scala/collection/parallel/ParSeqLike.scala +++ b/src/library/scala/collection/parallel/ParSeqLike.scala @@ -146,8 +146,6 @@ self => executeAndWaitResult(new SegmentLength(p, 0, splitter.psplit(realfrom, length - realfrom)(1) assign ctx))._1 } - def prefixLength(p: T => Boolean) = segmentLength(p, 0) - /** Finds the first element satisfying some predicate. * * $indexsignalling @@ -166,14 +164,6 @@ self => executeAndWaitResult(new IndexWhere(p, realfrom, splitter.psplit(realfrom, length - realfrom)(1) assign ctx)) } - def indexWhere(p: T => Boolean): Int = indexWhere(p, 0) - - def findIndexOf(p: T => Boolean): Int = indexWhere(p, 0) - - def indexOf[U >: T](elem: U): Int = indexOf(elem, 0) - - def indexOf[U >: T](elem: U, from: Int): Int = indexWhere(elem ==, from) - /** Finds the last element satisfying some predicate. * * $indexsignalling @@ -200,8 +190,6 @@ self => executeAndWaitResult(new ReverseMap[S, That](f, pbf, splitter) mapResult { _.result }) } otherwise seq.reverseMap(f)(bf2seq(bf)) - def startsWith[S](that: GenSeq[S]): Boolean = startsWith(that, 0) - /** Tests whether this $coll contains the given sequence at a given index. * * $abortsignalling @@ -226,7 +214,7 @@ self => length == pthat.length && executeAndWaitResult(new SameElements(splitter assign ctx, pthat.splitter)) } otherwise seq.sameElements(that) - /** Tests whether this $coll ends with the given parallel sequence + /** Tests whether this $coll ends with the given parallel sequence. * * $abortsignalling * @@ -328,7 +316,7 @@ self => * If an element value `x` appears * ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained * in the result, but any following occurrences will be omitted. - * @usecase def intersect(that: Seq[A]): $Coll[A] + * @usecase def intersect(that: Seq[T]): $Coll[T] * @return a new $coll which contains all elements of this $coll * which also appear in `that`. * If an element value `x` appears diff --git a/test/files/run/pc-conversions.scala b/test/files/run/pc-conversions.scala index 8f6a7744d9..6be0f99355 100644 --- a/test/files/run/pc-conversions.scala +++ b/test/files/run/pc-conversions.scala @@ -49,8 +49,13 @@ object Test { assertToPar(parallel.immutable.ParHashSet(1 -> 3)) assertToParWoMap(immutable.Range(1, 10, 2)) + + // seq and par again conversions) + assertSeqPar(parallel.mutable.ParArray(1, 2, 3)) } + def assertSeqPar[T](pc: parallel.ParIterable[T]) = pc.seq.par == pc + def assertSeq[T](pc: parallel.ParIterable[T]) = assert(pc.seq == pc) def assertPar[T, P <: Parallel](xs: GenIterable[T]) = assert(xs == xs.par) |