Merge pull request scala#7379 from nasadorian/either-filterToOption

Rename Either's `filter` method to `filterToOption`

Author: lrytz

src/library/scala/util/Either.scala

@@ -621,11 +621,26 @@ object Either {
      *  Right(12).left.filter(_ > 10) // None
      *  }}}
      */
+    @deprecated("Use `filterToOption`, which more accurately reflects the return type", "2.13.0")
     def filter[B1](p: A => Boolean): Option[Either[A, B1]] = e match {
       case x @ Left(a) if p(a) => Some(x.asInstanceOf[Either[A, B1]])
       case _                   => None
     }
 
+    /** Returns `None` if this is a `Right` or if the given predicate
+     *  `p` does not hold for the left value, otherwise, returns a `Left`.
+     *
+     *  {{{
+     *  Left(12).left.filterToOption(_ > 10)  // Some(Left(12))
+     *  Left(7).left.filterToOption(_ > 10)   // None
+     *  Right(12).left.filterToOption(_ > 10) // None
+     *  }}}
+     */
+    def filterToOption[B1](p: A => Boolean): Option[Either[A, B1]] = e match {
+      case x @ Left(a) if p(a) => Some(x.asInstanceOf[Either[A, B1]])
+      case _                   => None
+    }
+    
     /** Returns a `Seq` containing the `Left` value if it exists or an empty
      *  `Seq` if this is a `Right`.
      *
@@ -764,11 +779,27 @@ object Either {
      * Left(12).right.filter(_ > 10)  // None
      * }}}
      */
+    @deprecated("Use `filterToOption`, which more accurately reflects the return type", "2.13.0")
     def filter[A1](p: B => Boolean): Option[Either[A1, B]] = e match {
       case Right(b) if p(b) => Some(Right(b))
       case _                => None
     }
-
+    
+    /** Returns `None` if this is a `Left` or if the
+     *  given predicate `p` does not hold for the right value,
+     *  otherwise, returns a `Right`.
+     *
+     * {{{
+     * Right(12).right.filterToOption(_ > 10) // Some(Right(12))
+     * Right(7).right.filterToOption(_ > 10)  // None
+     * Left(12).right.filterToOption(_ > 10)  // None
+     * }}}
+     */
+    def filterToOption[A1](p: B => Boolean): Option[Either[A1, B]] = e match {
+      case r @ Right(b) if p(b) => Some(r.asInstanceOf[Either[A1, B]])
+      case _                    => None
+    }
+    
     /** Returns a `Seq` containing the `Right` value if
      *  it exists or an empty `Seq` if this is a `Left`.
      *

test/scalacheck/CheckEither.scala

@@ -52,7 +52,7 @@ object CheckEitherTest extends Properties("Either") {
       def g(s: String) = s.reverse
       e.left.map(x => f(g(x))) == e.left.map(x => g(x)).left.map(f(_))})
 
-    val prop_filter = forAll((e: Either[Int, Int], x: Int) => e.left.filter(_ % 2 == 0) ==
+    val prop_filterToOption = forAll((e: Either[Int, Int], x: Int) => e.left.filterToOption(_ % 2 == 0) ==
       (if(e.isRight || e.left.get % 2 != 0) None else Some(e)))
 
     val prop_seq = forAll((e: Either[Int, Int]) => e.left.toSeq == (e match {
@@ -98,7 +98,7 @@ object CheckEitherTest extends Properties("Either") {
       def g(s: String) = s.reverse
       e.right.map(x => f(g(x))) == e.right.map(x => g(x)).right.map(f(_))})
 
-    val prop_filter = forAll((e: Either[Int, Int], x: Int) => e.right.filter(_ % 2 == 0) ==
+    val prop_filterToOption = forAll((e: Either[Int, Int], x: Int) => e.right.filterToOption(_ % 2 == 0) ==
       (if(e.isLeft || e.right.get % 2 != 0) None else Some(e)))
 
     val prop_seq = forAll((e: Either[Int, Int]) => e.right.toSeq == (e match {
@@ -202,7 +202,7 @@ object CheckEitherTest extends Properties("Either") {
       ("Left.prop_flatMapComposition", CheckLeftProjection.prop_flatMapComposition),
       ("Left.prop_mapIdentity", CheckLeftProjection.prop_mapIdentity),
       ("Left.prop_mapComposition", CheckLeftProjection.prop_mapComposition),
-      ("Left.prop_filter", CheckLeftProjection.prop_filter),
+      ("Left.prop_filterToOption", CheckLeftProjection.prop_filterToOption),
       ("Left.prop_seq", CheckLeftProjection.prop_seq),
       ("Left.prop_option", CheckLeftProjection.prop_option),
       ("Right.prop_value", CheckRightProjection.prop_value),
@@ -214,7 +214,7 @@ object CheckEitherTest extends Properties("Either") {
       ("Right.prop_flatMapComposition", CheckRightProjection.prop_flatMapComposition),
       ("Right.prop_mapIdentity", CheckRightProjection.prop_mapIdentity),
       ("Right.prop_mapComposition", CheckRightProjection.prop_mapComposition),
-      ("Right.prop_filter", CheckRightProjection.prop_filter),
+      ("Right.prop_filterToOption", CheckRightProjection.prop_filterToOption),
       ("Right.prop_seq", CheckRightProjection.prop_seq),
       ("Right.prop_option", CheckRightProjection.prop_option),
       ("prop_Either_left", prop_Either_left),