Merge pull request #1864 from Bhashit/issue-1856-box-combinator-and-other-improvements

Add transform and flip methods.

transform allows callers to take a Box and, via PartialFunction, turn it into any
other Box. If the PartialFunction fails, the original Box is returned.

flip allows callers to take a Box and, if it is an EmptyBox, flip it into a Full box
with a specific type. If it is a Full, an Empty is returned, flipping the box from
full to empty or vice versa.

Author: Shadowfiend

core/common/src/main/scala/net/liftweb/common/Box.scala

@@ -167,8 +167,9 @@ sealed trait BoxTrait {
    * @return A `Full` containing the transformed value if
    *         `pf.isDefinedAt(value)` and `Empty` otherwise.
    */
-  def apply[InType, OutType](pf: PartialFunction[InType, OutType])(value: InType): Box[OutType] =
-  if (pf.isDefinedAt(value)) Full(pf(value)) else Empty
+  def apply[InType, OutType](pf: PartialFunction[InType, OutType])(value: InType): Box[OutType] = {
+    apply(value)(pf)
+  }
 
   /**
    * Apply the specified `PartialFunction` to the specified `value` and return
@@ -180,8 +181,9 @@ sealed trait BoxTrait {
    * @return A `Full` containing the transformed value if
    *         `pf.isDefinedAt(value)` and `Empty` otherwise.
    */
-  def apply[InType, OutType](value: InType)(pf: PartialFunction[InType, OutType]): Box[OutType] =
-  if (pf.isDefinedAt(value)) Full(pf(value)) else Empty
+  def apply[InType, OutType](value: InType)(pf: PartialFunction[InType, OutType]): Box[OutType] = {
+    pf.andThen(Full.apply).applyOrElse(value, (_:  InType) => Empty)
+  }
 
   /**
    * This implicit transformation allows one to use a `Box` as an `Iterable` of
@@ -549,18 +551,18 @@ sealed abstract class Box[+A] extends Product with Serializable{
    */
   def asA[B](implicit m: Manifest[B]): Box[B] = Empty
 
-  /**
-   * Return this Box if `Full`, or the specified alternative if it is
-   * empty. Equivalent to `Option`'s `[[scala.Option.orElse orElse]]`.
-   */
-  def or[B >: A](alternative: => Box[B]): Box[B] = alternative
-
   /**
    * Returns an `[[scala.collection.Iterator Iterator]]` over the value
    * contained in this `Box`, if any.
    */
   def elements: Iterator[A] = Iterator.empty
 
+  /**
+    * Return this Box if `Full`, or the specified alternative if it is
+    * empty. Equivalent to `Option`'s `[[scala.Option.orElse orElse]]`.
+    */
+  def or[B >: A](alternative: => Box[B]): Box[B]
+
   /**
    * Get a `java.util.Iterator` from the Box.
    */
@@ -773,10 +775,8 @@ sealed abstract class Box[+A] extends Product with Serializable{
    * If the partial function is defined at the current Box's value, apply the
    * partial function.
    */
-  final def collect[B](pf: PartialFunction[A, B]): Box[B] = {
-    flatMap(value =>
-    if (pf.isDefinedAt(value)) Full(pf(value))
-    else Empty)
+  final def collect[B](pf: PartialFunction[A, B]): Box[B] = flatMap { value =>
+    Box(value)(pf)
   }
 
   /**
@@ -788,6 +788,47 @@ sealed abstract class Box[+A] extends Product with Serializable{
   final def collectFirst[B](pf: PartialFunction[A, B]): Box[B] = {
     collect(pf)
   }
+
+  /**
+    * Transforms this box using the `transformFn`. If `transformFn` is defined for this box,
+    * returns the result of applying `transformFn` to it. Otherwise, returns this box unchanged.
+    *
+    * If you want to change the content of a `Full` box, using `[[map]]` or `[[collect]]` might be better
+    * suited to that purpose. If you want to convert an `Empty`, `Failure` or a `ParamFailure` into a
+    * `Full` box, you should use `[[flip]]`.
+    *
+    * @example {{{
+    *
+    *  // Returns Full("alternative") because the partial function covers the case.
+    *  Full("error") transform { case Full("error") => Full("alternative") }
+    *
+    *  // Returns Full(1), this Full box unchanged, because the partial function doesn't cover the case.
+    *  Full(1) transform { case Full(2) => Failure("error") }
+    *
+    *  // Returns this Failure("another-error") unchanged because the partial function doesn't cover the case.
+    *  Failure("another-error") transform { case Failure("error", Empty, Empty) => Full("alternative") }
+    *
+    *  // Returns Full("alternative") for an Empty box since `partialFn` is defined for Empty
+    *  Empty transform { case Empty => Full("alternative") }
+    *
+    *  // Returns Empty because the partial function is not defined for Empty
+    *  Empty transform { case Failure("error", Empty, Empty) => Full("alternative") }
+    *
+    *  }}}
+    */
+  def transform[B >: A](transformFn: PartialFunction[Box[A], Box[B]]): Box[B] = {
+    transformFn.applyOrElse(this, (thisBox: Box[A]) => thisBox)
+  }
+
+  /**
+    * Returns a `Full` box containing the results of applying `flipFn` to this box if it is a `Failure`,
+    * `ParamFailure` or `Empty`. Returns `Empty` if this box is `Full`. In other words, it "flips" the
+    * full/empty status of this Box.
+    */
+  def flip[B](flipFn: EmptyBox => B): Box[B] = this match {
+    case e: EmptyBox => Full(flipFn(e))
+    case _ => Empty
+  }
 }
 
 /**

core/common/src/test/scala/net/liftweb/common/BoxSpec.scala

@@ -67,8 +67,8 @@ class BoxSpec extends Specification with ScalaCheck with BoxGenerator {
       Full(1) reduceLeft {(x: Int, y: Int) => x + y} must_== 1
     }
     "be used as an Option" in {
-      Full(1) orElse Some(2) must_== Some(1)
-      Empty orElse Some(2) must_== Some(2)
+      Full(1) orElse Some(2) must beSome(1)
+      Empty orElse Some(2) must beSome(2)
     }
     "be implicitly defined from an Option. The openOrThrowException method can be used on an Option for example" in {
       Some(1).openOrThrowException("This is a test") must_== 1
@@ -152,14 +152,38 @@ class BoxSpec extends Specification with ScalaCheck with BoxGenerator {
         Full(Empty).flatten must_== Empty
       }
     }
+    "define a 'collect' method that takes a PartialFunction to transform its contents" in {
+      "If the partial-function is defined for the contents of this box, returns a full box containing the result of applying that partial function to this Box's contents" in {
+        Full("Albus") collect { case "Albus" => "Dumbledore"} must_== Full("Dumbledore")
+      }
+      "If the partial-function is not defined for the contents of this box, returns Empty" in {
+        Full("Hermione") collect { case "Albus" => "Dumbledore"} must beEmpty
+      }
+    }
+    "define a 'transform' method that takes a PartialFunction to transform this box into another box" in {
+      "If the partial-function is defined for this box, returns the result of applying the partial function to it" in {
+        Full(404) transform {
+          case Full(x: Int) if x != 200 => Failure("Server error")
+        } must_== Failure("Server error")
+      }
+      "If the partial-function is not defined for this box, returns itself unchanged" in {
+        Full("Intended Result") transform {
+          case _: EmptyBox => Full("Alternative")
+          case Full("Unexpected Result") => Full("Alternative")
+        } must_== Full("Intended Result")
+      }
+    }
+    "define a 'flip' method returning Empty" in {
+      Full(1) flip { _ => "No data found" } mustEqual Empty
+    }
     "define an 'elements' method returning an iterator containing its value" in {
       Full(1).elements.next must_== 1
     }
     "define a 'toList' method returning a List containing its value" in {
       Full(1).toList must_== List(1)
     }
     "define a 'toOption' method returning a Some object containing its value" in {
-      Full(1).toOption must_== Some(1)
+      Full(1).toOption must beSome(1)
     }
     "return itself if asked for its status with the operator ?~" in {
       Full(1) ?~ "error" must_== Full(1)
@@ -298,14 +322,34 @@ class BoxSpec extends Specification with ScalaCheck with BoxGenerator {
     "define a 'flatten' method returning Empty" in {
       Empty.flatten must beEmpty
     }
+    "define a 'collect' method returning Empty" in {
+      Empty collect { case _ => "Some Value" } must beEmpty
+    }
+    "define a 'transform' method that takes a PartialFunction to transform this Empty box into another box" in {
+      "If the partial-function is defined for Empty, returns the result of applying the partial function to it" in {
+        Empty transform {
+          case Failure("error", Empty, Empty) => Full("failure-alternative")
+          case Empty => Full("alternative")
+        } must_== Full("alternative")
+      }
+      "If the partial-function is not defined for Empty, returns Empty" in {
+        Empty transform { case Failure("The Phantom Menace", Empty, Empty) => Full("Return Of The Jedi") } must_== Empty
+      }
+    }
+    "define a 'flip' method returning a Full box" in {
+      Empty flip {
+        case Empty => "flipped-empty"
+        case _ => "flipped-failure"
+      } mustEqual Full("flipped-empty")
+    }
     "define an 'elements' method returning an empty iterator" in {
       Empty.elements.hasNext must beFalse
     }
     "define a 'toList' method returning Nil" in {
       Empty.toList must_== Nil
     }
     "define a 'toOption' method returning None" in {
-      Empty.toOption must_== None
+      Empty.toOption must beNone
     }
     "return a failure with a message if asked for its status with the operator ?~" in {
       Empty ?~ "nothing" must_== Failure("nothing", Empty, Empty)
@@ -358,7 +402,31 @@ class BoxSpec extends Specification with ScalaCheck with BoxGenerator {
       Failure("error", Empty, Empty) flatMap {x: String => Full(x.toString)} must_== Failure("error", Empty, Empty)
       Failure("error", Empty, Empty).flatten must_== Failure("error", Empty, Empty)
     }
-    "return a itself when asked for its status with the operator ?~" in {
+    "define a 'collect' method returning itself" in {
+      Failure("error", Empty, Empty) collect { case _ => "Some Value" } must_== Failure("error", Empty, Empty)
+    }
+    "define a 'transform' method that takes a PartialFunction to transform this Failure into another box" in {
+      "If the partial-function is defined for this Failure, returns the result of applying the partial function to it" in {
+        Failure("The Phantom Menace") transform {
+          case Failure("The Phantom Menace", Empty, Empty) => Full("Return Of The Jedi")
+        } must_== Full("Return Of The Jedi")
+
+        Failure("The Phantom Menace") transform {
+          case Failure("The Phantom Menace", Empty, Empty) => Failure("Clones")
+          case _ => Full("Jedi")
+        } must_== Failure("Clones")
+      }
+      "If the partial-function is not defined for this Failure, returns itself unchanged" in {
+        Failure("Clones") transform { case Failure("The Phantom Menace", Empty, Empty) => Full("Jedi") } must_== Failure("Clones")
+      }
+    }
+    "define a 'flip' method returning a Full box" in {
+      Failure("error", Empty, Empty) flip {
+        case Empty => "flipped-empty"
+        case _: Failure => "flipped-failure"
+      } must_== Full("flipped-failure")
+    }
+    "return itself when asked for its status with the operator ?~" in {
       Failure("error", Empty, Empty) ?~ "nothing" must_== Failure("error", Empty, Empty)
     }
     "create a new failure with a chained message if asked for its status with the operator ?~!" in {