Package scala.util.control
package control
Type Members
class Breaks extends AnyRef
trait ControlThrowable extends Throwable with NoStackTrace
A marker trait indicating that the Throwable it is mixed into is intended for flow control.
Note that Throwable subclasses which extend this trait may extend any other Throwable subclass (eg. RuntimeException) and are not required to extend Throwable directly.
Instances of Throwable subclasses marked in this way should not normally be caught. Where catch-all behaviour is required ControlThrowable should be propagated, for example:
import scala.util.control.ControlThrowable
try {
// Body might throw arbitrarily
} catch {
case c: ControlThrowable => throw c // propagate
case t: Exception => log(t) // log and suppress
}
trait NoStackTrace extends Throwable
A trait for exceptions which, for efficiency reasons, do not fill in the stack trace. Stack trace suppression can be disabled on a global basis via a system property wrapper in scala.sys.SystemProperties.
- Since
2.8
- Note
Since JDK 1.7, a similar effect can be achieved with
class Ex extends Throwable(..., writableStackTrace = false)
Value Members
object Breaks extends Breaks
An object that can be used for the break control abstraction. Example usage:
import Breaks.{break, breakable}
breakable {
for (...) {
if (...) break
}
}
object Exception
Classes representing the components of exception handling.
Each class is independently composable.
This class differs from scala.util.Try in that it focuses on composing exception handlers rather than composing behavior. All behavior should be composed first and fed to a Catch object using one of the opt, either or withTry methods. Taken together the classes provide a DSL for composing catch and finally behaviors.
Examples
Create a Catch which handles specified exceptions.
import scala.util.control.Exception._
import java.net._
val s = "http://www.scala-lang.org/"
// Some(http://www.scala-lang.org/)
val x1: Option[URL] = catching(classOf[MalformedURLException]) opt new URL(s)
// Right(http://www.scala-lang.org/)
val x2: Either[Throwable,URL] =
catching(classOf[MalformedURLException], classOf[NullPointerException]) either new URL(s)
// Success(http://www.scala-lang.org/)
val x3: Try[URL] = catching(classOf[MalformedURLException], classOf[NullPointerException]) withTry new URL(s)
val defaultUrl = new URL("http://example.com")
// URL(http://example.com) because htt/xx throws MalformedURLException
val x4: URL = failAsValue(classOf[MalformedURLException])(defaultUrl)(new URL("htt/xx"))
Create a Catch which logs exceptions using handling and by.
def log(t: Throwable): Unit = t.printStackTrace
val withThrowableLogging: Catch[Unit] = handling(classOf[MalformedURLException]) by (log)
def printUrl(url: String) : Unit = {
val con = new URL(url) openConnection()
val source = scala.io.Source.fromInputStream(con.getInputStream())
source.getLines.foreach(println)
}
val badUrl = "htt/xx"
// Prints stacktrace,
// java.net.MalformedURLException: no protocol: htt/xx
// at java.net.URL.<init>(URL.java:586)
withThrowableLogging { printUrl(badUrl) }
val goodUrl = "http://www.scala-lang.org/"
// Prints page content,
// <!DOCTYPE html>
// <html>
withThrowableLogging { printUrl(goodUrl) }
Use unwrapping to create a Catch that unwraps exceptions before rethrowing.
class AppException(cause: Throwable) extends RuntimeException(cause) val unwrappingCatch: Catch[Nothing] = unwrapping(classOf[AppException]) def calcResult: Int = throw new AppException(new NullPointerException) // Throws NPE not AppException, // java.lang.NullPointerException // at .calcResult(<console>:17) val result = unwrappingCatch(calcResult)
Use failAsValue to provide a default when a specified exception is caught.
val inputDefaulting: Catch[Int] = failAsValue(classOf[NumberFormatException])(0) val candidatePick = "seven" // scala.io.StdIn.readLine() // Int = 0 val pick = inputDefaulting(candidatePick.toInt)
Compose multiple Catchs with or to build a Catch that provides default values varied by exception.
val formatDefaulting: Catch[Int] = failAsValue(classOf[NumberFormatException])(0)
val nullDefaulting: Catch[Int] = failAsValue(classOf[NullPointerException])(-1)
val otherDefaulting: Catch[Int] = nonFatalCatch withApply(_ => -100)
val combinedDefaulting: Catch[Int] = formatDefaulting or nullDefaulting or otherDefaulting
def p(s: String): Int = s.length * s.toInt
// Int = 0
combinedDefaulting(p("tenty-nine"))
// Int = -1
combinedDefaulting(p(null: String))
// Int = -100
combinedDefaulting(throw new IllegalStateException)
// Int = 22
combinedDefaulting(p("11"))
object NoStackTrace extends Serializable
object NonFatal
Extractor of non-fatal Throwables. Will not match fatal errors like VirtualMachineError (for example, OutOfMemoryError and StackOverflowError, subclasses of VirtualMachineError), ThreadDeath, LinkageError, InterruptedException, ControlThrowable.
Note that scala.util.control.ControlThrowable, an internal Throwable, is not matched by NonFatal (and would therefore be thrown).
For example, all harmless Throwables can be caught by:
try {
// dangerous stuff
} catch {
case NonFatal(e) => log.error(e, "Something not that bad.")
// or
case e if NonFatal(e) => log.error(e, "Something not that bad.")
}
object TailCalls
Methods exported by this object implement tail calls via trampolining. Tail calling methods have to return their result using done or call the next method using tailcall. Both return a TailRec object. The result of evaluating a tailcalling function can be retrieved from a Tailrec value using method result. Implemented as described in "Stackless Scala with Free Monads" http://blog.higher-order.com/assets/trampolines.pdf
Here's a usage example:
import scala.util.control.TailCalls._
def isEven(xs: List[Int]): TailRec[Boolean] =
if (xs.isEmpty) done(true) else tailcall(isOdd(xs.tail))
def isOdd(xs: List[Int]): TailRec[Boolean] =
if (xs.isEmpty) done(false) else tailcall(isEven(xs.tail))
isEven((1 to 100000).toList).result
def fib(n: Int): TailRec[Int] =
if (n < 2) done(n) else for {
x <- tailcall(fib(n - 1))
y <- tailcall(fib(n - 2))
} yield (x + y)
fib(40).result
© 2002-2019 EPFL, with contributions from Lightbend.
Licensed under the Apache License, Version 2.0.
https://www.scala-lang.org/api/2.12.9/scala/util/control/index.html
A class that can be instantiated for the break control abstraction. Example usage:
val mybreaks = new Breaks import mybreaks.{break, breakable} breakable { for (...) { if (...) break() } }Calls to break from one instantiation of
Breakswill never target breakable objects of some other instantiation.