Add sectionon union types

Author: odersky

docs/docs/reference/intersection-types.md

@@ -63,4 +63,3 @@ class C extends A with B {
   def children: List[A & B] = ???
 }
 ```
-

docs/docs/reference/union-types.md

@@ -0,0 +1,57 @@
+---
+layout: doc-page
+title: "Union Types"
+---
+
+Used on types, the `|` operator creates a union type.
+
+```scala
+case class UserName(name: String) {
+  def lookup(admin: Admin): UserData
+}
+case class Password(hash: Hash) {
+  def lookup(admin: Admin): UserData
+}
+
+def help(id: UserName | PassWord) = {
+  val user = id match {
+    case UserName(name) => lookupName(name)
+    case Password(hash) => lookupPassword(hash)
+  }
+  // ...
+}
+```
+
+Union types are dual of intersection types. Values of type `A | B` are
+all values of type `A` and all values of type `B`. `|` is _commutative_:
+`A | B` is the same type as `B | A`.
+
+The compiler will assign an expression a union type only if such a
+type is explicitly given.
+This can be seen in the folling REPL
+transcript:
+
+```scala
+scala> val password = Password(123)
+val password: Password = Password(123)
+scala> val name = UserName("Eve")
+val name: UserName = UserName(Eve)
+scala> if (true) name else password
+val res2: Object & Product = UserName(Eve)
+scala> val either: Password | UserName = if (true) name else password
+val either: Password | UserName = UserName(Eve)
+```
+
+The type of `res2` is `Object | Product`, which is a supertype of
+`UserName` and `Product, but not the least supertype `Password |
+UserName`.  If we want the least supertype, we have to give it
+explicitely, as is done for the type of `Either`. More precisely, the
+typechecker will _widen_ a union type to a non-union type when
+inferring the type of ` `val` or `var`, or the result type of a `def`,
+or the argument to pass for a type parameter.  The widened type of `A
+| B` is usually the intersection of all class or trait types that are
+supertypes of both `A` and `B`; it does not include any refinements.
+Union types are in that sense analogous to singleton types `x.type`
+which are also widened to their underlying type unless explicitly
+specified.
+

docs/sidebar.yml

@@ -3,6 +3,10 @@ sidebar:
       url: blog/index.html
     - title: Reference
       subsection:
+        - title: Intersection types
+          url: docs/reference/intersection-types.html
+        - title: Union types
+          url: docs/reference/union-types.html
         - title: Trait Parameters
           url: docs/reference/trait-parameters.html
         - title: Enumerations

tests/pos/intersection.scala

@@ -15,4 +15,10 @@ object intersection {
 
   type needsA = A => Nothing
   type needsB = B => Nothing
+
+
+  class C[-T]
+  def f: C[A] & C[B] = ???
+  def g: C[A | B] = f
+  def h: C[A] & C[B] = g
 }

tests/pos/reference/union-types.scala

@@ -0,0 +1,37 @@
+package unionTypes
+
+object t1 {
+
+type Hash = Int
+
+case class UserName(name: String)
+case class Password(hash: Hash)
+
+def help(id: UserName | Password) = {
+  val user = id match {
+    case UserName(name) => lookupName(name)
+    case Password(hash) => lookupPassword(hash)
+  }
+}
+
+def lookupName(name: String) = ???
+def lookupPassword(hash: Hash) = ???
+
+}
+
+object t2 {
+  import t1._
+
+trait Admin
+trait UserData
+
+trait L { def lookup(admin: Admin): Object }
+
+case class UserName(name: String) extends L {
+  def lookup(admin: Admin): UserData = ???
+}
+case class Password(hash: Hash) extends L {
+  def lookup(admin: Admin): UserData = ???
+}
+
+}