Removing toPar* methods, since we've agreed the...

Removing toPar* methods, since we've agreed they're difficult to: -
underestand - maintain

Also, changed the docs and some tests appropriately.

Description:
1) Every collection is now parallelizable - switch to the parallel version of the collection is done via `par`.

- Traversable collections and iterators have `par` return a parallel
- collection of type `ParIterable[A]` with the implementation being the
- representative of `ParIterable`s (currently, `ParArray`). Iterable
- collections do the same thing. Sequences refine `par`'s returns type
- to `ParSeq[A]`. Maps and sets do a similar thing.

The above means that the contract for `par` changed - it is no longer guaranteed to be O(1), nor reflect the same underlying data, as was the case for mutable collections before. Method `par` is now at worst linear.

Furthermore, specific collection implementations override `par` to a more efficient alternative - instead of copying the dataset, the dataset is shared between the old and the new version. Implementation complexity may be sublinear or constant in these cases, and the underlying data structure may be shared. Currently, these data structures include parallel arrays, maps and sets, vectors, hash trie maps and sets, and ranges.

Finally, parallel collections implement `par` trivially.

2) Methods `toMap`, `toSet`, `toSeq` and `toIterable` have been refined
for parallel collections to switch between collection types, however,
they never switch an implementation from parallel to sequential. They
may or may not copy the elements, as is the case with sequential
variants of these methods.

3) The preferred way to switch between different collection types,
whether maps, sets and seqs, or parallel and sequential, is now via use
of methods `toIterable`, `toSeq`, `toSet` and `toMap` in combination
with `par` and `seq`.

Review by odersky.

3 files changed, 64 insertions, 43 deletions

diff --git a/test/files/run/coder/Coder.scala b/test/files/run/coder/Coder.scala
index 5c81efc9c0..06dd4b6355 100644
--- a/test/files/run/coder/Coder.scala
+++ b/test/files/run/coder/Coder.scala
@@ -85,7 +85,7 @@ class ParCoder(words: List[String]) {
   def encode(number: String): ParSet[List[String]] =
     if (number.isEmpty) ParSet(List())
     else {
-      val splits = (1 to number.length).toParSet
+      val splits = (1 to number.length).toSet.par
       // for {
       //   split <- splits
       //   word <- wordsForNum(number take split)
diff --git a/test/files/run/coder2/Coder2.scala b/test/files/run/coder2/Coder2.scala
index 7ecc5e67d1..abe284a398 100644
--- a/test/files/run/coder2/Coder2.scala
+++ b/test/files/run/coder2/Coder2.scala
@@ -77,7 +77,7 @@ class ParCoder(words: List[String]) {
    *  them e.g. `5282` -> List(`Java`, `Kata`, `Lava`, ...)
    */
   val wordsForNum: Map[String, ParSeq[String]] =
-    (words groupBy wordCode).map(t => (t._1, t._2.toParSeq)) withDefaultValue ParSeq()
+    (words groupBy wordCode).map(t => (t._1, t._2.toSeq.par)) withDefaultValue ParSeq()
 
   val comparison = new SeqCoder(words)
 
@@ -85,7 +85,7 @@ class ParCoder(words: List[String]) {
   def encode(number: String): ParSet[ParSeq[String]] =
     if (number.isEmpty) ParSet(ParSeq())
     else {
-      val splits = (1 to number.length).toParSet
+      val splits = (1 to number.length).toSet.par
       // for {
       //   split <- splits
       //   word <- wordsForNum(number take split)
@@ -118,7 +118,7 @@ class ParCoder(words: List[String]) {
 
   def assertWfn(num: String, split: String, dropped: String, r: ParSeq[ParSeq[String]]) {
     val m = comparison.wfnmemo((num, split))
-    val rs = r.toParSet
+    val rs = r.toSet.par
     val words: ParSeq[String] = wordsForNum(split)
     if (rs != m) {
       println("flatmap for number with split: " + num + ", " + split)
@@ -168,32 +168,32 @@ object Test {
 
   /* */
   def main(args : Array[String]) {
-    // for (i <- 0 until 10) {
-    //   val seqcoder = new SeqCoder(Dictionary.wordlist)
-    //   val st = seqcoder.translate(code)
-    //   //println("Translation check: " + st.size)
-
-    //   val parcoder = new ParCoder(Dictionary.wordlist)
-    //   val pt = parcoder.translate(code)
-    //   //println("Translation check: " + pt.size)
-
-    //   // val st = sts.toList.sorted
-    //   // val pt = pts.toList.sorted
-    //   if (st.size != pt.size) {
-    //     // val zipped = st.zip(pt)
-    //     // val ind = zipped.indexWhere { case (a, b) => a != b }
-    //     // val sliced = zipped.slice(ind - 10, ind + 10)
-    //     // println(sliced.map(t => t._1 + "\n" + t._2 + "\n--------").mkString("\n"))
-    //     println(i + ") seq vs par: " + st.size + " vs " + pt.size)
-    //   }
-    //   if (st != pt) {
-    //     val zipped = (st.toList.sorted zip pt.toList.sorted);
-    //     val diffp = zipped indexWhere { case (x, y) => x != y }
-    //     println(zipped/*.slice(diffp - 10, diffp + 10)*/ mkString ("\n"))
-    //     println((st.toList.sorted zip pt.toList.sorted) map { case (x, y) => (x == y) } reduceLeft(_ && _))
-    //   }
-    //   assert(st == pt)
-    // }
+    for (i <- 0 until 10) {
+      val seqcoder = new SeqCoder(Dictionary.wordlist)
+      val sts = seqcoder.translate(code)
+      //println("Translation check: " + st.size)
+
+      val parcoder = new ParCoder(Dictionary.wordlist)
+      val pts = parcoder.translate(code)
+      //println("Translation check: " + pt.size)
+
+      val st = sts.toList.sorted
+      val pt = pts.toList.sorted
+      if (st.size != pt.size) {
+        val zipped = st.zip(pt)
+        val ind = zipped.indexWhere { case (a, b) => a != b }
+        val sliced = zipped.slice(ind - 10, ind + 10)
+        //println(sliced.map(t => t._1 + "\n" + t._2 + "\n--------").mkString("\n"))
+        //println(i + ") seq vs par: " + st.size + " vs " + pt.size)
+      }
+      if (st != pt) {
+        val zipped = (st.toList.sorted zip pt.toList.sorted);
+        val diffp = zipped indexWhere { case (x, y) => x != y }
+        //println(zipped/*.slice(diffp - 10, diffp + 10)*/ mkString ("\n"))
+        //println((st.toList.sorted zip pt.toList.sorted) map { case (x, y) => (x == y) } reduceLeft(_ && _))
+      }
+      assert(st == pt)
+    }
   }
 }
 
diff --git a/test/files/run/pc-conversions.scala b/test/files/run/pc-conversions.scala
index 7e894f70f3..23fcb9fa59 100644
--- a/test/files/run/pc-conversions.scala
+++ b/test/files/run/pc-conversions.scala
@@ -30,7 +30,7 @@ object Test {
     assertPar(immutable.HashMap(1 -> 1, 2 -> 2))
     assertPar(immutable.HashSet(1, 2, 3))
 
-    // toPar*
+    // par.to* and to*.par tests
     assertToPar(List(1 -> 1, 2 -> 2, 3 -> 3))
     assertToPar(Stream(1 -> 1, 2 -> 2))
     assertToPar(Array(1 -> 1, 2 -> 2))
@@ -55,28 +55,49 @@ object Test {
 
   def assertSeq[T](pc: parallel.ParIterable[T]) = assert(pc.seq == pc)
 
-  def assertPar[T, P <: Parallel](xs: Iterable[T] with Parallelizable[P]) = assert(xs == xs.par)
+  def assertPar[T, P <: Parallel](xs: Iterable[T]) = assert(xs == xs.par)
 
   def assertToPar[K, V](xs: Traversable[(K, V)]) {
     xs match {
-      case _: Seq[_] => assert(xs.toParIterable == xs)
+      case _: Seq[_] =>
+        assert(xs.toIterable.par == xs)
+        assert(xs.par.toIterable == xs)
       case _ =>
     }
-    assert(xs.toParSeq == xs.toSeq)
-    assert(xs.toParSet == xs.toSet)
-    assert(xs.toParMap == xs.toMap)
+
+    assert(xs.toSeq.par == xs.toSeq)
+    assert(xs.par.toSeq == xs.toSeq)
+
+    assert(xs.toSet.par == xs.toSet)
+    assert(xs.par.toSet == xs.toSet)
+
+    assert(xs.toMap.par == xs.toMap)
+    assert(xs.par.toMap == xs.toMap)
   }
 
-  def assertToParWoMap[T](xs: Traversable[T]) {
-    assert(xs.toParIterable == xs)
-    assert(xs.toParSeq == xs.toSeq)
-    assert(xs.toParSet == xs.toSet)
+  def assertToParWoMap[T](xs: Seq[T]) {
+    assert(xs.toIterable.par == xs.toIterable)
+    assert(xs.par.toIterable == xs.toIterable)
+
+    assert(xs.toSeq.par == xs.toSeq)
+    assert(xs.par.toSeq == xs.toSeq)
+
+    assert(xs.toSet.par == xs.toSet)
+    assert(xs.par.toSet == xs.toSet)
   }
 
   def assertToParIt[K, V](xs: =>Iterator[(K, V)]) {
-    assert(xs.toParSeq == xs.toSeq)
-    assert(xs.toParSet == xs.toSet)
-    assert(xs.toParMap == xs.toMap)
+    assert(xs.toIterable.par == xs.toIterable)
+    assert(xs.par.toIterable == xs.toIterable)
+
+    assert(xs.toSeq.par == xs.toSeq)
+    assert(xs.par.toSeq == xs.toSeq)
+
+    assert(xs.toSet.par == xs.toSet)
+    assert(xs.par.toSet == xs.toSet)
+
+    assert(xs.toMap.par == xs.toMap)
+    assert(xs.par.toMap == xs.toMap)
   }
 
 }