Scala Standard Library 2.13.16 - scala.util.control
Keywords: Scala Standard Library 2.13.16 scala.util.control

Scala Standard Library2.13.16 < Back


# Packages

-  package root

  This is the documentation for the Scala standard library.

  This is the documentation for the Scala standard library.

  #### Package structure

  The scala package contains core types like `Int`, `Float`, `Array` or `Option` which are accessible in all Scala compilation units without explicit qualification or imports.

  Notable packages include:

  - `scala.collection` and its sub-packages contain Scala's collections framework
    - `scala.collection.immutable` - Immutable, sequential data-structures such as `Vector`, `List`, `Range`, `HashMap` or `HashSet`
    - `scala.collection.mutable` - Mutable, sequential data-structures such as `ArrayBuffer`, `StringBuilder`, `HashMap` or `HashSet`
    - `scala.collection.concurrent` - Mutable, concurrent data-structures such as `TrieMap`
  - `scala.concurrent` - Primitives for concurrent programming such as `Futures` and `Promises`
  - `scala.io` - Input and output operations
  - `scala.math` - Basic math functions and additional numeric types like `BigInt` and `BigDecimal`
  - `scala.sys` - Interaction with other processes and the operating system
  - `scala.util.matching` - Regular expressions

  Other packages exist. See the complete list on the right.

  Additional parts of the standard library are shipped as separate libraries. These include:

  - `scala.reflect` - Scala's reflection API (scala-reflect.jar)
  - `scala.xml` - XML parsing, manipulation, and serialization (scala-xml.jar)
  - `scala.collection.parallel` - Parallel collections (scala-parallel-collections.jar)
  - `scala.util.parsing` - Parser combinators (scala-parser-combinators.jar)
  - `scala.swing` - A convenient wrapper around Java's GUI framework called Swing (scala-swing.jar)

  #### Automatic imports

  Identifiers in the scala package and the `scala.Predef` object are always in scope by default.

  Some of these identifiers are type aliases provided as shortcuts to commonly used classes. For example, `List` is an alias for `scala.collection.immutable.List`.

  Other aliases refer to classes provided by the underlying platform. For example, on the JVM, `String` is an alias for `java.lang.String`.

  Definition Classes
    root
-  package scala

  Core Scala types.

  Core Scala types. They are always available without an explicit import.

  Definition Classes
    root
-  package util
  Definition Classes
    scala
-  package control
  Definition Classes
    util
- Breaks
- ControlThrowable
- Exception
- NoStackTrace
- NonFatal
- TailCalls
-  package hashing
  Definition Classes
    util
-  package matching
  Definition Classes
    util

p

scala.util

# control

#### package control

Content Hierarchy

Ordering

1. Alphabetic

Visibility

1. Public
2. Protected

### Type Members

1.  class Breaks extends AnyRef

   Provides the `break` control abstraction.

   Provides the `break` control abstraction.

   The `break` method uses a `ControlThrowable` to transfer control up the stack to an enclosing `breakable`.

   It is typically used to abruptly terminate a `for` loop, but can be used to return from an arbitrary computation.

   Control resumes after the `breakable`.

   If there is no matching `breakable`, the `BreakControl` thrown by `break` is handled in the usual way: if not caught, it may terminate the current `Thread`.

   `BreakControl` carries no stack trace, so the default exception handler does not print useful diagnostic information; there is no compile-time warning if there is no matching `breakable`.

   A catch clause using `NonFatal` is safe to use with `break`; it will not short-circuit the transfer of control to the enclosing `breakable`.

   A `breakable` matches a call to `break` if the methods were invoked on the same receiver object, which may be the convenience value `Breaks`.

   Example usage:

       val mybreaks = new Breaks
       import mybreaks.{break, breakable}

       breakable {
         for (x <- xs) {
           if (done) break()
           f(x)
         }
       }

   Calls to `break` from one instance of `Breaks` will never resume at the `breakable` of some other instance.

   Any intervening exception handlers should use `NonFatal`, or use `Try` for evaluation:

       val mybreaks = new Breaks
       import mybreaks.{break, breakable}

       breakable {
         for (x <- xs) Try { if (quit) break else f(x) }.foreach(println)
       }

2.  abstract class ControlThrowable extends Throwable

   A parent class for throwable objects intended for flow control.

   A parent class for throwable objects intended for flow control.

   Instances of `ControlThrowable` should not normally be caught.

   As a convenience, `NonFatal` does not match `ControlThrowable`.

       import scala.util.control.{Breaks, NonFatal}, Breaks.{break, breakable}

       breakable {
         for (v <- values) {
           try {
             if (p(v)) break
             else ???
           } catch {
             case NonFatal(t) => log(t)  // can't catch a break
           }
         }
       }

   Suppression is disabled, because flow control should not suppress an exceptional condition. Stack traces are also disabled, allowing instances of `ControlThrowable` to be safely reused.

   Instances of `ControlThrowable` should not normally have a cause. Legacy subclasses may set a cause using `initCause`.

3.  trait NoStackTrace extends Throwable

   A trait for exceptions which, for efficiency reasons, do not fill in the stack trace.

   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.

   Note

     Since JDK 1.7, a similar effect can be achieved with `class Ex extends Throwable(..., writableStackTrace = false)`

### Value Members

1.  object Breaks extends Breaks

   An object that can be used for the break control abstraction.

   An object that can be used for the break control abstraction.

   Example usage:

       import Breaks.{break, breakable}

       breakable {
         for (...) {
           if (...) break
         }
       }

2.  object Exception

   Classes representing the components of exception handling.

   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 = "https://www.scala-lang.org/"

       // Some(https://www.scala-lang.org/)
       val x1: Option[URL] = catching(classOf[MalformedURLException]) opt new URL(s)

       // Right(https://www.scala-lang.org/)
       val x2: Either[Throwable,URL] =
         catching(classOf[MalformedURLException], classOf[NullPointerException]) either new URL(s)

       // Success(https://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 = "https://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 `Catch`s 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"))

3.  object NoStackTrace extends java.io.Serializable
4.  object NonFatal

   Extractor of non-fatal Throwables.

   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.")
       }

5.  object TailCalls

   Methods exported by this object implement tail calls via trampolining.

   Methods exported by this object implement tail calls via trampolining.

   Tail calling methods must either return their result using `done` or call the next method using `tailcall`. Both return an instance of `TailRec`. 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" https://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

### Ungrouped