Merge pull request scala#7111 from Atry/extractor

Converters among optional Functions, PartialFunctions and extractor objects

Author: SethTisue

src/build/genprod.scala

@@ -59,6 +59,7 @@ object genprod extends App {
 
     def genprodString       = " See scala.Function0 for timestamp."
     def moreMethods         = ""
+    def companionObject     = ""
     def packageDef          = "scala"
     def imports             = ""
 
@@ -150,6 +151,36 @@ object FunctionOne extends Function(1) {
    *  @return       a new function `f` such that `f(x) == g(apply(x))`
    */
   @annotation.unspecialized def andThen[A](g: R => A): T1 => A = { x => g(apply(x)) }
+"""
+  override def companionObject =
+"""
+object Function1 {
+
+  implicit final class UnliftOps[A, B] private[Function1](private val f: A => Option[B]) extends AnyVal {
+    /** Converts an optional function to a partial function.
+      *
+      * @example Unlike [[Function.unlift]], this [[UnliftOps.unlift]] method can be used in extractors.
+      *          {{{
+      *          val of: Int => Option[String] = { i =>
+      *            if (i == 2) {
+      *              Some("matched by an optional function")
+      *            } else {
+      *              None
+      *            }
+      *          }
+      *
+      *          util.Random.nextInt(4) match {
+      *            case of.unlift(m) => // Convert an optional function to a pattern
+      *              println(m)
+      *            case _ =>
+      *              println("Not matched")
+      *          }
+      *          }}}
+      */
+    def unlift: PartialFunction[A, B] = Function.unlift(f)
+  }
+
+}
 """
 }
 
@@ -192,7 +223,7 @@ class Function(val i: Int) extends Group("Function") with Arity {
   def toStr() = "\"" + ("<function%d>" format i) + "\""
   def apply() = {
 <file name={fileName}>{header}
-
+{companionObject}
 /** A function of {i} parameter{s}.
  *{descriptiveComment}
  */

src/library/scala/Function1.scala

@@ -15,6 +15,34 @@
 package scala
 
 
+object Function1 {
+
+  implicit final class UnliftOps[A, B] private[Function1](private val f: A => Option[B]) extends AnyVal {
+    /** Converts an optional function to a partial function.
+      *
+      * @example Unlike [[Function.unlift]], this [[UnliftOps.unlift]] method can be used in extractors.
+      *          {{{
+      *          val of: Int => Option[String] = { i =>
+      *            if (i == 2) {
+      *              Some("matched by an optional function")
+      *            } else {
+      *              None
+      *            }
+      *          }
+      *
+      *          util.Random.nextInt(4) match {
+      *            case of.unlift(m) => // Convert an optional function to a pattern
+      *              println(m)
+      *            case _ =>
+      *              println("Not matched")
+      *          }
+      *          }}}
+      */
+    def unlift: PartialFunction[A, B] = Function.unlift(f)
+  }
+
+}
+
 /** A function of 1 parameter.
  *  
  *  In the following example, the definition of succ is a

src/library/scala/PartialFunction.scala

@@ -52,13 +52,37 @@ package scala
  *  val numbers = sample map (isEven orElse isOdd)
  *  }}}
  *
+ *  @note Optional [[Function]]s, [[PartialFunction]]s and extractor objects
+ *        can be converted to each other as shown in the following table.
+ *
+ *        | How to convert ... | to a [[PartialFunction]] | to an optional [[Function]] | to an extractor |
+ *        | :---:  | ---  | --- | --- |
+ *        | from a [[PartialFunction]] | [[Predef.identity]] | [[lift]] | [[Predef.identity]] |
+ *        | from optional [[Function]] | [[Function.UnliftOps#unlift]] or [[Function.unlift]] | [[Predef.identity]] | [[Function.UnliftOps#unlift]] |
+ *        | from an extractor | `{ case extractor(x) => x }` | `extractor.unapply _` | [[Predef.identity]] |
  *
  *  @author  Martin Odersky, Pavel Pavlov, Adriaan Moors
  *  @since   1.0
  */
 trait PartialFunction[-A, +B] extends (A => B) { self =>
   import PartialFunction._
 
+  /** Tries to extract a `B` from an `A` in a pattern matching expression. */
+  def unapply(a: A): Option[B] = lift(a)
+
+  /** Returns an extractor object with a `unapplySeq` method, which extracts each element of a sequence data.
+   *
+   *  @example {{{
+   *           val firstChar: String => Option[Char] = _.headOption
+   *
+   *           Seq("foo", "bar", "baz") match {
+   *             case firstChar.unlift.elementWise(c0, c1, c2) =>
+   *               println(s"$c0, $c1, $c2") // Output: f, b, b
+   *           }
+   *           }}}
+   */
+  def elementWise = new ElementWiseExtractor(this)
+
   /** Checks if a value is contained in the function's domain.
    *
    *  @param  x   the value to test
@@ -202,6 +226,16 @@ trait PartialFunction[-A, +B] extends (A => B) { self =>
  *  @since   2.8
  */
 object PartialFunction {
+
+  final class ElementWiseExtractor[-A, +B] private[PartialFunction] (private val pf: PartialFunction[A, B]) extends AnyVal {
+    def unapplySeq(seq: Seq[A]): Option[Seq[B]] = {
+      Some(seq.map {
+        case pf(b) => b
+        case _ => return None
+      })
+    }
+  }
+
   /** Composite function produced by `PartialFunction#orElse` method
    */
   private class OrElse[-A, +B] (f1: PartialFunction[A, B], f2: PartialFunction[A, B])

test/junit/scala/ExtractorTest.scala

@@ -0,0 +1,78 @@
+package scala
+
+import org.junit.Assert._
+import org.junit.Test
+
+import scala.tools.testkit.RunTesting
+
+class ExtractorTest extends RunTesting {
+  val of: Int => Option[String] = { x =>
+    if (x == 0) {
+      Some("zero")
+    } else if (x == 1) {
+      Some("one")
+    } else {
+      None
+    }
+  }
+
+  @Test def testOptionalFunctionExtractor(): Unit = {
+    1 match {
+      case of.unlift(m) =>
+        assertEquals(m, "one")
+    }
+  }
+
+  @Test(expected = classOf[MatchError]) def testOptionalFunctionExtractorMatchError(): Unit = {
+    2 match {
+      case of.unlift(m) =>
+    }
+  }
+
+  @Test def testOptionalFunctionExtractorSeq(): Unit = {
+    Seq(0, 1) match {
+      case of.unlift.elementWise(m0, m1) =>
+        assertEquals(m0, "zero")
+        assertEquals(m1, "one")
+    }
+  }
+
+  @Test(expected = classOf[MatchError]) def testOptionalFunctionExtractorSeqMatchError(): Unit = {
+    Seq(1, 2) match {
+      case of.unlift.elementWise(m0, m1) =>
+    }
+  }
+
+  val pf: PartialFunction[Int, String] = {
+    case 0 => "zero"
+    case 1 => "one"
+  }
+
+  @Test def testPartialFunctionExtractor(): Unit = {
+    1 match {
+      case pf(m) =>
+        assertEquals(m, "one")
+    }
+  }
+
+  @Test(expected = classOf[MatchError]) def testPartialFunctionExtractorMatchError(): Unit = {
+    2 match {
+      case pf(m) =>
+    }
+  }
+
+  @Test def testPartialFunctionExtractorSeq(): Unit = {
+    Seq(0, 1) match {
+      case pf.elementWise(m0, m1) =>
+        assertEquals(m0, "zero")
+        assertEquals(m1, "one")
+    }
+  }
+
+  @Test(expected = classOf[MatchError]) def testPartialFunctionExtractorSeqMatchError(): Unit = {
+    Seq(1, 2) match {
+      case pf.elementWise(m0, m1) =>
+    }
+  }
+
+}