Merge remote-tracking branch 'origin/develop'

7 files changed, 83 insertions, 6 deletions

diff --git a/src/compiler/scala/tools/nsc/ast/parser/MarkupParsers.scala b/src/compiler/scala/tools/nsc/ast/parser/MarkupParsers.scala
index 7388ecf163..46ade7d889 100644
--- a/src/compiler/scala/tools/nsc/ast/parser/MarkupParsers.scala
+++ b/src/compiler/scala/tools/nsc/ast/parser/MarkupParsers.scala
@@ -117,7 +117,7 @@ trait MarkupParsers {
      *                      | `{` scalablock `}`
      */
     def xAttributes = {
-      val aMap = mutable.HashMap[String, Tree]()
+      val aMap = mutable.LinkedHashMap[String, Tree]()
 
       while (isNameStart(ch)) {
         val start = curOffset
diff --git a/src/library/scala/Function1.scala b/src/library/scala/Function1.scala
index dc8e67bbb0..7517e6604b 100644
--- a/src/library/scala/Function1.scala
+++ b/src/library/scala/Function1.scala
@@ -24,10 +24,18 @@ package scala
  *    assert(succ(0) == anonfun1(0))
  *  }
  *  }}}
+ *
+ *  Note that `Function1` does not define a total function, as might
+ *  be suggested by the existence of [[scala.PartialFunction]]. The only
+ *  distinction between `Function1` and `PartialFunction` is that the
+ *  latter can specify inputs which it will not handle.
+ *
  */
 @annotation.implicitNotFound(msg = "No implicit view available from ${T1} => ${R}.")
 trait Function1[@specialized(scala.Int, scala.Long, scala.Float, scala.Double) -T1, @specialized(scala.Unit, scala.Boolean, scala.Int, scala.Float, scala.Long, scala.Double) +R] extends AnyRef { self =>
-  /** Apply the body of this function to the argument.
+  /** Apply the body of this function to the argument. It may throw an
+   *  exception.
+   *
    *  @return   the result of function application.
    */
   def apply(v1: T1): R
diff --git a/src/library/scala/PartialFunction.scala b/src/library/scala/PartialFunction.scala
index b2910c2278..70caff0221 100644
--- a/src/library/scala/PartialFunction.scala
+++ b/src/library/scala/PartialFunction.scala
@@ -13,6 +13,36 @@ package scala
  *  The function `isDefinedAt` allows to test dynamically if a value is in
  *  the domain of the function.
  *
+ *  Even if `isDefinedAt` returns true for an `a: A`, calling `apply(a)` may
+ *  still throw an exception, so the following code is legal:
+ *
+ *  {{{
+ *  val f: PartialFunction[Int, Any] = { case _ => 1/0 }
+ *  }}}
+ *
+ *  The main distinction between `PartialFunction` and [[scala.Function1]] is
+ *  that the user of a `PartialFunction` may choose to do something different
+ *  with input that is declared to be outside its domain. For example:
+ *
+ *  {{{
+ *  val sample = 1 to 10
+ *  val isEven: PartialFunction[Int, String] = { 
+ *    case x if x % 2 == 0 => x+" is even" 
+ *  }
+ *
+ *  // the method collect can use isDefinedAt to select which members to collect
+ *  val evenNumbers = sample collect isEven
+ *
+ *  val isOdd: PartialFunction[Int, String] = { 
+ *    case x if x % 2 == 1 => x+" is odd" 
+ *  }
+ *
+ *  // the method orElse allows chaining another partial function to handle 
+ *  // input outside the declared domain
+ *  val numbers = sample map (isEven orElse isOdd)
+ *  }}}
+ *
+ *
  *  @author  Martin Odersky
  *  @version 1.0, 16/07/2003
  */
diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala
index 122eec2d90..c837775cf9 100644
--- a/src/library/scala/collection/GenTraversableLike.scala
+++ b/src/library/scala/collection/GenTraversableLike.scala
@@ -177,7 +177,28 @@ trait GenTraversableLike[+A, +Repr] extends GenTraversableOnce[A] with Paralleli
   def collect[B, That](pf: PartialFunction[A, B])(implicit bf: CanBuildFrom[Repr, B, That]): That
 
   /** Builds a new collection by applying a function to all elements of this $coll
-   *  and concatenating the results.
+   *  and using the elements of the resulting collections. For example:
+   *
+   *  {{{
+   *  def getWords(lines: Seq[String]): Seq[String] = lines flatMap (line => line split "\\W+")
+   *  }}}
+   *
+   *  The type of the resulting collection is guided by the static type of $coll. This might
+   *  cause unexpected results sometimes. For example:
+   *
+   *  {{{
+   *  // lettersOf will return a Seq[Char] of likely repeated letters, instead of a Set
+   *  def lettersOf(words: Seq[String]) = words flatMap (word => word.toSet)
+   *
+   *  // lettersOf will return a Set[Char], not a Seq
+   *  def lettersOf(words: Seq[String]) = words.toSet flatMap (word => word.toSeq)
+   *
+   *  // xs will be a an Iterable[Int]
+   *  val xs = Map("a" -> List(11,111), "b" -> List(22,222)).flatMap(_._2)
+   *
+   *  // ys will be a Map[Int, Int]
+   *  val ys = Map("a" -> List(1 -> 11,1 -> 111), "b" -> List(2 -> 22,2 -> 222)).flatMap(_._2)
+   *  }}}
    *
    *  @param f      the function to apply to each element.
    *  @tparam B     the element type of the returned collection.
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index e2acc0b3e0..b4813e6341 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -709,6 +709,9 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr]
      *  outer $coll containing this `WithFilter` instance that satisfy
      *  predicate `p` and concatenating the results.
      *
+     *  The type of the resulting collection will be guided by the static type
+     *  of the outer $coll.
+     *
      *  @param f      the function to apply to each element.
      *  @tparam B     the element type of the returned collection.
      *  @tparam That  $thatinfo
diff --git a/src/library/scala/collection/generic/GenericTraversableTemplate.scala b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
index 12c1a75c7a..7333074778 100644
--- a/src/library/scala/collection/generic/GenericTraversableTemplate.scala
+++ b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
@@ -116,7 +116,19 @@ trait GenericTraversableTemplate[+A, +CC[X] <: GenTraversable[X]] extends HasNew
   }
 
   /** Converts this $coll of traversable collections into
-   *  a $coll in which all element collections are concatenated.
+   *  a $coll formed by the elements of these traversable
+   *  collections.
+   *
+   *  The resulting collection's type will be guided by the
+   *  static type of $coll. For example:
+   *
+   *  {{{
+   *  val xs = List(Set(1, 2, 3), Set(1, 2, 3))
+   *  // xs == List(1, 2, 3, 1, 2, 3)
+   *
+   *  val ys = Set(List(1, 2, 3), List(3, 2, 1))
+   *  // ys == Set(1, 2, 3)
+   *  }}}
    *
    *  @tparam B the type of the elements of each traversable collection.
    *  @param asTraversable an implicit conversion which asserts that the element
diff --git a/src/partest/scala/tools/partest/nest/PathSettings.scala b/src/partest/scala/tools/partest/nest/PathSettings.scala
index f6353faa6f..04f36ffa11 100644
--- a/src/partest/scala/tools/partest/nest/PathSettings.scala
+++ b/src/partest/scala/tools/partest/nest/PathSettings.scala
@@ -16,6 +16,9 @@ object PathSettings {
 
   private def cwd = Directory.Current getOrElse sys.error("user.dir property not set")
   private def isPartestDir(d: Directory) = (d.name == "test") && (d / srcDirName isDirectory)
+  private def findJar(d: Directory, name: String): Option[File] = findJar(d.files, name)
+  private def findJar(files: Iterator[File], name: String): Option[File] =
+    files filter (_ hasExtension "jar") find { _.name startsWith name }
 
   // Directory <root>/test
   lazy val testRoot: Directory = testRootDir getOrElse {
@@ -33,7 +36,7 @@ object PathSettings {
   // Directory <root>/test/files/speclib
   lazy val srcSpecLibDir = Directory(srcDir / "speclib")
 
-  lazy val srcSpecLib: File = srcSpecLibDir.files find (_.name startsWith "instrumented") getOrElse {
+  lazy val srcSpecLib: File = findJar(srcSpecLibDir, "instrumented") getOrElse {
     sys.error("No instrumented.jar found in %s".format(srcSpecLibDir))
   }
 
@@ -51,7 +54,7 @@ object PathSettings {
   lazy val buildPackLibDir = Directory(buildDir / "pack" / "lib")
 
   lazy val scalaCheck: File =
-    buildPackLibDir.files ++ srcLibDir.files find (_.name startsWith "scalacheck") getOrElse {
+    findJar(buildPackLibDir.files ++ srcLibDir.files, "scalacheck") getOrElse {
       sys.error("No scalacheck jar found in '%s' or '%s'".format(buildPackLibDir, srcLibDir))
     }
 }