Box
Related Docs:
object Box
| package common
Makes Box play better with Scala for comprehensions.
Returns true if this Box contains no value (i.e., it is Empty or
Failure or ParamFailure).
The only time when you should be using this method is if the value is guaranteed to be available based on a guard outside of the method.
The only time when you should be using this method is if the value is
guaranteed to be available based on a guard outside of the method. In these
cases, please provide that information in the justification String.
For example, User.currentUser.openOrThrowException("This snippet is only
used on pages where the user is logged in"). For tests, use == or
=== instead. See the class documentation for more information.
A valid justification for using this method should not be "I want my code to fail fast when I call it." Using exceptions in the core logic of your application should be strongly discouraged.
Justify why calling this method is okay and why it will not result in an exception being thrown. This serves both as mandatory documentation and as a very clear indication of what unexpected thing happened in the event you were wrong about the guard.
The contents of the Box if it is Full.
NullPointerException If you attempt to call it on an EmptyBox,
with a message that includes the provided justification.
Alias for pass.
Returns true if the value contained in this box is equal to the specified value.
Returns true if the value contained in this box is equal to the specified
value. This is the same thing that == does when it's handed a value that
isn't a Box, but using this is recommended because it's clearer that the
behavior will be different than the usual expectation.
Transform an Empty to a Failure with the specified message.
Transform an Empty to a Failure with the specified message. Otherwise
returns the same box.
A Failure with the message if this Box is Empty, this box
otherwise.
This means a Failure will also remain unchanged; see ?~! to
change these.
Chain the given msg as a Failure ahead of any failures this Box may
represent.
Chain the given msg as a Failure ahead of any failures this Box may
represent.
If this is an Empty, this method behaves like ?~. If it is a Failure,
however, this method returns a new Failure with the given msg and with its
chain set to this Failure.
As with ?~, if this is a Full, we return it unchanged.
A Failure with the message if this Box is an Empty box. Chain
this box to the new Failure if this is a Failure. The unchanged
box if it is a Full.
Create a Full box containing the specified value if this box's value is
of type B and Empty otherwise.
Create a Full box containing the specified value if this box's value is
of type B and Empty otherwise.
For example:
scala> Full("boom").asA[Int] res0: net.liftweb.common.Box[Int] = Empty scala> Full(5).asA[Int] res1: net.liftweb.common.Box[Int] = Full(5)
Equivalent to flatMap(f1).or(alternative).
If the partial function is defined at the current Box's value, apply the partial function.
An alias for collect.
An alias for collect.
Although this function is different for true collections, because Box is
really a collection of 1, the two functions are identical.
Alias for ?~!.
Equivalent to map(f).openOr(dflt).
Returns an Iterator over the value
contained in this Box, if any.
For Full and Empty, this has the expected behavior.
For Full and Empty, this has the expected behavior. Equality in terms
of Failure checks for equivalence of failure causes:
Failure("boom") == Failure("boom") Failure("bam") != Failure("boom") Failure("boom", Full(someException), Empty) != Failure("boom")
For other values, determines equality based upon the contents of this Box
instead of the box itself. As a result, it is not symmetric. As an example:
val foo = "foo" val boxedFoo = Full(foo) foo == boxedFoo //is false boxedFoo == foo //is true
It is safest to use === explicitly when you're looking for this behavior,
and use == only for box-to-box comparisons:
Full("magic") == Full("magic") Full("magic") != Full("another") Full("magic") != Empty Full("magic") != Failure("something's gone wrong")
If this Box contains a value and it satisfies the specified func,
return true.
If this Box contains a value and it satisfies the specified func,
return true. Otherwise, return false.
true if this Box does contain a value and it satisfies the
predicate.
Alias for ?~.
If this Box contains a value and it satisfies the specified predicate,
return the Box unchanged.
If this Box contains a value and it satisfies the specified predicate,
return the Box unchanged. Otherwise, return an Empty.
If this Box contains a value and it satisfies the specified predicate,
return the Box unchanged.
If this Box contains a value and it satisfies the specified predicate,
return the Box unchanged. Otherwise, return a Failure with the given
msg.
A Failure with the message if the box is empty or the predicate
is not satisfied by the value contained in this Box.
If this Box contains a value and it does not satisfy the specified
f, return the Box unchanged.
If this Box contains a value and it does not satisfy the specified
f, return the Box unchanged. Otherwise, return an Empty.
Apply a function returning a Box to the value contained in this Box if
it exists and return the resulting Box.
Apply a function returning a Box to the value contained in this Box if
it exists and return the resulting Box. If this Box is not already
Full, return this box unchanged.
This means that using flatMap with a Failure will preserve the
Failure.
If this Box contains a value and it does not satisfy the specified
func, return false.
If this Box contains a value and it does not satisfy the specified
func, return false. Otherwise, return true.
true If the Box is empty, or if its value satisfies the
predicate.
Perform a side effect by calling the specified function with the value contained in this box.
Perform a side effect by calling the specified function with the value
contained in this box. The function does not run if this Box is empty.
If the Box is Full, apply the transform function f on the value v;
otherwise, just return the value untransformed.
If the Box is Full, apply the transform function f on the value v;
otherwise, just return the value untransformed.
The transform function is expected to be a function that will take the
value v and produce a function from the value in the box to a new value
of the same type as v.
For example:
val myBox = Full(10) myBox.fullXForm("No teddy bears left.")({ message => { teddyBears: Int => s"$message Oh wait, there are $teddyBears left!" } })
The type of the initial value, default value, and transformed value.
If the Box is Full, the value once transformed by the function
returned by f. Otherwise, the initial value v.
Exists to avoid the implicit conversion from Box to Option.
Exists to avoid the implicit conversion from Box to Option. Opening a
Box unsafely should be done using openOrThrowException.
This method always throws an exception.
If this box is Full and contains an object of type B, returns a Full
of type Box[B].
If this box is Full and contains an object of type B, returns a Full
of type Box[B]. Otherwise, returns Empty.
This is basically a Java-friendly version of asA, which you should
prefer when using Scala.
For example:
scala> Full("boom").isA(classOf[Int]) res0: net.liftweb.common.Box[Int] = Empty scala> Full(5).isA(classOf[Int]) res1: net.liftweb.common.Box[Int] = Full(5)
Returns true if the box contains a value.
Returns an Iterator over the value
contained in this Box, if any.
Get a java.util.Iterator from the Box.
Apply a function to the value contained in this Box if it exists and return
a Full containing the result.
Apply a function to the value contained in this Box if it exists and return
a Full containing the result. If this Box is not already Full, return
the unchanged box.
This means that using map with a Failure will preserve the
Failure.
Return the value contained in this Box if it is full; otherwise return
the specified default.
Return the value contained in this Box if it is full; otherwise return
the specified default. Equivalent to Option's getOrElse.
Return this Box if Full, or the specified alternative if it is
empty.
Return this Box if Full, or the specified alternative if it is
empty. Equivalent to Option's orElse.
Perform a side effect by passing this Box to the specified function and
return this Box unmodified.
Perform a side effect by passing this Box to the specified function and
return this Box unmodified. Similar to foreach, except that foreach
returns Unit, while this method allows chained use of the Box.
This box.
This method calls the specified function with the specified in value and
the value contained in this Box.
This method calls the specified function with the specified in value and
the value contained in this Box. If this box is empty, returns the in
value directly.
The result of the function or the in value.
An Either that is a Right with the given argument
right if this is empty, or a Left with the boxed value if this is
Full.
Returns a List of one element if this
is Full, or an empty list if empty.
Returns the contents of this box wrapped in Some if this is Full, or
None if this is empty (meaning an Empty, Failure or ParamFailure).
An Either that is a Left with the given argument
left if this is empty, or a Right with the boxed value if this is
Full.
Makes Box play better with Scala for comprehensions.
Transform an Empty or Failure to a ParamFailure with the specified
type-safe parameter.
Transform an Empty or Failure to a ParamFailure with the specified
type-safe parameter.
A value indicating the error.
A ParamFailure with the specified value, unless this is already a
ParamFailure or a Full. If this is a Failure, the
ParamFailure will preserve the message of the Failure.
The
Boxclass is a container which is able to declare if it isFull(containing a single non-null value) orEmptyBox. AnEmptyBox, or empty, can be theEmptysingleton,FailureorParamFailure.FailureandParamFailurecontain information about why theBoxis empty including exception information, possibly chainedFailures and aStringmessage.This serves a similar purpose to the
Optionclass from Scala standard library but adds several features:Failureobject if it isEmpty(with the?~orfailMsgmethod).Failures (with the?~!orcompoundFailMsgmethod).Box, with a default to return if the box isEmpty:Boxto a function for side effects:Exceptions and Empty Box Handling
If you grew up on Java, you're used to
Exceptions as part of your program logic. The Scala philosophy and the Lift philosophy is that exceptions are for exceptional conditions such as failure of an external resource (e.g., your database goes offline) rather than simply indicating that a parameter wasn't supplied or couldn't be parsed.Lift's
Boxand Scala'sOptionprovide mechanisms for being explicit about a value existing or not existing rather than relying on a reference being not-null. However, extracting a value from aBoxshould be done correctly. Available options are:forcomprehension, especially for multiple boxes:map,flatMap,filter, andforeach(forcomprehensions use these under the covers):Failures):==and===: