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

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 annotation
  Definition Classes
    scala
-  package beans
  Definition Classes
    scala
-  package collection
  Definition Classes
    scala
-  package compat
  Definition Classes
    scala
-  package concurrent

  This package object contains primitives for concurrent and parallel programming.

  This package object contains primitives for concurrent and parallel programming.

  #### Guide

  A more detailed guide to Futures and Promises, including discussion and examples can be found at https://docs.scala-lang.org/overviews/core/futures.html.

  #### Common Imports

  When working with Futures, you will often find that importing the whole concurrent package is convenient:

      import scala.concurrent._

  When using things like `Future`s, it is often required to have an implicit `ExecutionContext` in scope. The general advice for these implicits are as follows.

  If the code in question is a class or method definition, and no `ExecutionContext` is available, request one from the caller by adding an implicit parameter list:

      def myMethod(myParam: MyType)(implicit ec: ExecutionContext) = …
      //Or
      class MyClass(myParam: MyType)(implicit ec: ExecutionContext) { … }

  This allows the caller of the method, or creator of the instance of the class, to decide which `ExecutionContext` should be used.

  For typical REPL usage and experimentation, importing the global `ExecutionContext` is often desired.

      import scala.concurrent.ExcutionContext.Implicits.global

  #### Specifying Durations

  Operations often require a duration to be specified. A duration DSL is available to make defining these easier:

      import scala.concurrent.duration._
      val d: Duration = 10.seconds

  #### Using Futures For Non-blocking Computation

  Basic use of futures is easy with the factory method on Future, which executes a provided function asynchronously, handing you back a future result of that function without blocking the current thread. In order to create the Future you will need either an implicit or explicit ExecutionContext to be provided:

      import scala.concurrent._
      import ExecutionContext.Implicits.global  // implicit execution context

      val firstZebra: Future[Int] = Future {
        val words = Files.readAllLines("/etc/dictionaries-common/words").asScala
        words.indexOfSlice("zebra")
      }

  #### Avoid Blocking

  Although blocking is possible in order to await results (with a mandatory timeout duration):

      import scala.concurrent.duration._
      Await.result(firstZebra, 10.seconds)

  and although this is sometimes necessary to do, in particular for testing purposes, blocking in general is discouraged when working with Futures and concurrency in order to avoid potential deadlocks and improve performance. Instead, use callbacks or combinators to remain in the future domain:

      val animalRange: Future[Int] = for {
        aardvark <- firstAardvark
        zebra <- firstZebra
      } yield zebra - aardvark

      animalRange.onSuccess {
        case x if x > 500000 => println("It's a long way from Aardvark to Zebra")
      }

  Definition Classes
    scala
-  package io
  Definition Classes
    scala
-  package jdk

  The jdk package contains utilities to interact with JDK classes.

  The jdk package contains utilities to interact with JDK classes.

  This packages offers a number of converters, that are able to wrap or copy types from the scala library to equivalent types in the JDK class library and vice versa:

  - CollectionConverters, converting collections like scala.collection.Seq, scala.collection.Map, scala.collection.Set, scala.collection.mutable.Buffer, scala.collection.Iterator and scala.collection.Iterable to their JDK counterparts
  - OptionConverters, converting between Option and java.util.Optional and primitive variations
  - StreamConverters, to create JDK Streams from scala collections
  - DurationConverters, for conversions between scala scala.concurrent.duration.FiniteDuration and java.time.Duration
  - FunctionConverters, from scala Functions to java java.util.function.Function, java.util.function.UnaryOperator, java.util.function.Consumer and java.util.function.Predicate, as well as primitive variations and Bi-variations.

  By convention, converters that wrap an object to provide a different interface to the same underlying data structure use .asScala and .asJava extension methods, whereas converters that copy the underlying data structure use .toScala and .toJava.

  In the javaapi package, the same converters can be found with a java-friendly interface that don't rely on implicit enrichments.

  Additionally, this package offers Accumulators, capable of efficiently traversing JDK Streams.

  Definition Classes
    scala
-  package math

  The package object `scala.math` contains methods for performing basic numeric operations such as elementary exponential, logarithmic, root and trigonometric functions.

  The package object `scala.math` contains methods for performing basic numeric operations such as elementary exponential, logarithmic, root and trigonometric functions.

  All methods forward to java.lang.Math unless otherwise noted.

  Definition Classes
    scala
  See also

    java.lang.Math

-  package ref
  Definition Classes
    scala
-  package reflect
  Definition Classes
    scala
-  package sys

  The package object `scala.sys` contains methods for reading and altering core aspects of the virtual machine as well as the world outside of it.

  The package object `scala.sys` contains methods for reading and altering core aspects of the virtual machine as well as the world outside of it.

  Definition Classes
    scala
-  package util
  Definition Classes
    scala
-  package control
-  package hashing
-  package matching
- ChainingOps
- ChainingSyntax
- DynamicVariable
- Either
- Failure
- Left
- Properties
- Random
- Right
- Sorting
- Success
- Try
- Using
- chaining

p

scala

# util

#### package util

Source
  package.scala

Linear Supertypes
AnyRef, Any
Content Hierarchy

Ordering

1. Alphabetic
2. By Inheritance

Inherited

1. util
2. AnyRef
3. Any

1. Hide All
2. Show All

Visibility

1. Public
2. Protected

### Package Members

1.  package control
2.  package hashing
3.  package matching

### Type Members

1.  final class ChainingOps[A] extends AnyVal

   Adds chaining methods `tap` and `pipe` to every type.

2.  trait ChainingSyntax extends AnyRef
3.  class DynamicVariable[T] extends AnyRef

   `DynamicVariables` provide a binding mechanism where the current value is found through dynamic scope, but where access to the variable itself is resolved through static scope.

   `DynamicVariables` provide a binding mechanism where the current value is found through dynamic scope, but where access to the variable itself is resolved through static scope.

   The current value can be retrieved with the value method. New values should be pushed using the `withValue` method. Values pushed via `withValue` only stay valid while the `withValue`'s second argument, a parameterless closure, executes. When the second argument finishes, the variable reverts to the previous value.

       someDynamicVariable.withValue(newValue) {
         // ... code called in here that calls value ...
         // ... will be given back the newValue ...
       }

   Each thread gets its own stack of bindings. When a new thread is created, the `DynamicVariable` gets a copy of the stack of bindings from the parent thread, and from then on the bindings for the new thread are independent of those for the original thread.

4.  sealed abstract class Either[+A, +B] extends Product with Serializable

   Represents a value of one of two possible types (a disjoint union).

   Represents a value of one of two possible types (a disjoint union). An instance of `Either` is an instance of either scala.util.Left or scala.util.Right.

   A common use of `Either` is as an alternative to scala.Option for dealing with possibly missing values. In this usage, scala.None is replaced with a scala.util.Left which can contain useful information. scala.util.Right takes the place of scala.Some. Convention dictates that `Left` is used for failure and `Right` is used for success.

   For example, you could use `Either[String, Int]` to indicate whether a received input is a `String` or an `Int`.

       import scala.io.StdIn._
       val in = readLine("Type Either a string or an Int: ")
       val result: Either[String,Int] =
         try Right(in.toInt)
         catch {
           case e: NumberFormatException => Left(in)
         }

       result match {
         case Right(x) => s"You passed me the Int: $x, which I will increment. $x + 1 = ${x+1}"
         case Left(x)  => s"You passed me the String: $x"
       }

   `Either` is right-biased, which means that `Right` is assumed to be the default case to operate on. If it is `Left`, operations like `map` and `flatMap` return the `Left` value unchanged:

       def doubled(i: Int) = i * 2
       Right(42).map(doubled) // Right(84)
       Left(42).map(doubled)  // Left(42)

   Since `Either` defines the methods `map` and `flatMap`, it can also be used in for comprehensions:

       val right1 = Right(1)   : Right[Double, Int]
       val right2 = Right(2)
       val right3 = Right(3)
       val left23 = Left(23.0) : Left[Double, Int]
       val left42 = Left(42.0)

       for {
         x <- right1
         y <- right2
         z <- right3
       } yield x + y + z // Right(6)

       for {
         x <- right1
         y <- right2
         z <- left23
       } yield x + y + z // Left(23.0)

       for {
         x <- right1
         y <- left23
         z <- right2
       } yield x + y + z // Left(23.0)

       // Guard expressions are not supported:
       for {
         i <- right1
         if i > 0
       } yield i
       // error: value withFilter is not a member of Right[Double,Int]

       // Similarly, refutable patterns are not supported:
       for (x: Int <- right1) yield x
       // error: value withFilter is not a member of Right[Double,Int]

       // To use a filtered value, convert to an Option first,
       // which drops the Left case, as None contains no value:
       for {
         i <- right1.toOption
         if i > 0
       } yield i

   Since `for` comprehensions use `map` and `flatMap`, the types of function parameters used in the expression must be inferred. These types are constrained by the `Either` values. In particular, because of right-biasing, `Left` values may require an explicit type argument for type parameter `B`, the right value. Otherwise, it might be inferred as `Nothing`.

       for {
         x <- left23
         y <- right1
         z <- left42  // type at this position: Either[Double, Nothing]
       } yield x + y + z
       //            ^
       // error: ambiguous reference to overloaded definition,
       // both method + in class Int of type (x: Char)Int
       // and  method + in class Int of type (x: Byte)Int
       // match argument types (Nothing)

       for (x <- right2 ; y <- left23) yield x + y  // Left(23.0)
       for (x <- right2 ; y <- left42) yield x + y  // error

       for {
         x <- right1
         y <- left42  // type at this position: Either[Double, Nothing]
         z <- left23
       } yield x + y + z
       // Left(42.0), but unexpectedly a `Either[Double,String]`

5.  final case class Failure[+T](exception: Throwable) extends Try[T] with Product with Serializable
6.  final case class Left[+A, +B](value: A) extends Either[A, B] with Product with Serializable

   The left side of the disjoint union, as opposed to the scala.util.Right side.

7.  class Random extends Serializable
8.  final case class Right[+A, +B](value: B) extends Either[A, B] with Product with Serializable

   The right side of the disjoint union, as opposed to the scala.util.Left side.

9.  final case class Success[+T](value: T) extends Try[T] with Product with Serializable
10.  sealed abstract class Try[+T] extends Product with Serializable

    The `Try` type represents a computation that may fail during evaluation by raising an exception.

    The `Try` type represents a computation that may fail during evaluation by raising an exception. It holds either a successfully computed value or the exception that was thrown. This is similar to the scala.util.Either type, but with different semantics.

    Instances of `Try[T]` are an instance of either scala.util.Success[T] or scala.util.Failure[T].

    For example, consider a computation that performs division on user-defined input. `Try` can reduce or eliminate the need for explicit exception handling in all of the places where an exception might be thrown.

    Example:

        import scala.io.StdIn
        import scala.util.{Try, Success, Failure}

        def divide: Try[Int] = {
          val dividend = Try(StdIn.readLine("Enter an Int that you'd like to divide:\n").toInt)
          val divisor = Try(StdIn.readLine("Enter an Int that you'd like to divide by:\n").toInt)
          val problem = dividend.flatMap(x => divisor.map(y => x/y))
          problem match {
            case Success(v) =>
              println("Result of " + dividend.get + "/"+ divisor.get +" is: " + v)
              Success(v)
            case Failure(e) =>
              println("You must've divided by zero or entered something that's not an Int. Try again!")
              println("Info from the exception: " + e.getMessage)
              divide
          }
        }

    An important property of `Try` shown in the above example is its ability to pipeline, or chain, operations, catching exceptions along the way. The `flatMap` and `map` combinators in the above example each essentially pass off either their successfully completed value, wrapped in the `Success` type for it to be further operated upon by the next combinator in the chain, or the exception wrapped in the `Failure` type usually to be simply passed on down the chain. Combinators such as `recover` and `recoverWith` are designed to provide some type of default behavior in the case of failure.

    Note: only non-fatal exceptions are caught by the combinators on `Try` (see scala.util.control.NonFatal). Serious system errors, on the other hand, will be thrown.

    Note:: all Try combinators will catch exceptions and return failure unless otherwise specified in the documentation.

### Value Members

1.  object Either extends java.io.Serializable
2.  object Properties extends PropertiesTrait

   Loads `library.properties` from the jar.

3.  object Random extends Random

   The object `Random` offers a default implementation of scala.util.Random and random-related convenience methods.

4.  object Sorting

   The `Sorting` object provides convenience wrappers for `java.util.Arrays.sort`.

   The `Sorting` object provides convenience wrappers for `java.util.Arrays.sort`. Methods that defer to `java.util.Arrays.sort` say that they do or under what conditions that they do.

   `Sorting` also implements a general-purpose quicksort and stable (merge) sort for those cases where `java.util.Arrays.sort` could only be used at the cost of a large memory penalty. If performance rather than memory usage is the primary concern, one may wish to find alternate strategies to use `java.util.Arrays.sort` directly e.g. by boxing primitives to use a custom ordering on them.

   `Sorting` provides methods where you can provide a comparison function, or can request a sort of items that are scala.math.Ordered or that otherwise have an implicit or explicit scala.math.Ordering.

   Note also that high-performance non-default sorts for numeric types are not provided. If this is required, it is advisable to investigate other libraries that cover this use case.

5.  object Try extends java.io.Serializable
6.  object Using

   A utility for performing automatic resource management.

   A utility for performing automatic resource management. It can be used to perform an operation using resources, after which it releases the resources in reverse order of their creation.

   #### Usage

   There are multiple ways to automatically manage resources with `Using`. If you only need to manage a single resource, the `apply` method is easiest; it wraps the resource opening, operation, and resource releasing in a `Try`.

   Example:

       import java.io.{BufferedReader, FileReader}
       import scala.util.{Try, Using}

       val lines: Try[Seq[String]] =
         Using(new BufferedReader(new FileReader("file.txt"))) { reader =>
           Iterator.continually(reader.readLine()).takeWhile(_ != null).toSeq
         }

   If you need to manage multiple resources, `Using.Manager` should be used. It allows the managing of arbitrarily many resources, whose creation, use, and release are all wrapped in a `Try`.

   Example:

       import java.io.{BufferedReader, FileReader}
       import scala.util.{Try, Using}

       val files = List("file1.txt", "file2.txt", "file3.txt", "file4.txt")
       val lines: Try[Seq[String]] = Using.Manager { use =>
         // acquire resources
         def mkreader(filename: String) = use(new BufferedReader(new FileReader(filename)))

         // use your resources here
         def lines(reader: BufferedReader): Iterator[String] =
           Iterator.continually(reader.readLine()).takeWhile(_ != null)

         files.map(mkreader).flatMap(lines)
       }

   Composed or "wrapped" resources may be acquired in order of construction, if "underlying" resources are not closed. Although redundant in this case, here is the previous example with a wrapped call to `use`:

       def mkreader(filename: String) = use(new BufferedReader(use(new FileReader(filename))))

   Custom resources can be registered on construction by requiring an implicit `Manager`. This ensures they will be released even if composition fails:

       import scala.util.Using

       case class X(x: String)(implicit mgr: Using.Manager) extends AutoCloseable {
         override def close() = println(s"CLOSE $x")
         mgr.acquire(this)
       }
       case class Y(y: String)(x: String)(implicit mgr: Using.Manager) extends AutoCloseable {
         val xres = X(x)
         override def close() = println(s"CLOSE $y")
         // an error during construction releases previously acquired resources
         require(y != null, "y is null")
         mgr.acquire(this)
       }

       Using.Manager { implicit mgr =>
         val y = Y("Y")("X")
         println(s"USE $y")
       }
       println {
         Using.Manager { implicit mgr =>
           Y(null)("X")
         }
       } // Failure(java.lang.IllegalArgumentException: requirement failed: y is null)

   If you wish to avoid wrapping management and operations in a `Try`, you can use `Using.resource`, which throws any exceptions that occur.

   Example:

       import java.io.{BufferedReader, FileReader}
       import scala.util.Using

       val lines: Seq[String] =
         Using.resource(new BufferedReader(new FileReader("file.txt"))) { reader =>
           Iterator.continually(reader.readLine()).takeWhile(_ != null).toSeq
         }

   #### Suppression Behavior

   If two exceptions are thrown (e.g., by an operation and closing a resource), one of them is re-thrown, and the other is added to it as a suppressed exception. If the two exceptions are of different 'severities' (see below), the one of a higher severity is re-thrown, and the one of a lower severity is added to it as a suppressed exception. If the two exceptions are of the same severity, the one thrown first is re-thrown, and the one thrown second is added to it as a suppressed exception. If an exception is a `ControlThrowable`, or if it does not support suppression (see `Throwable`'s constructor with an `enableSuppression` parameter), an exception that would have been suppressed is instead discarded.

   Exceptions are ranked from highest to lowest severity as follows:

   - `java.lang.VirtualMachineError`
   - `java.lang.LinkageError`
   - `java.lang.InterruptedException` and `java.lang.ThreadDeath`
   - fatal exceptions, excluding `scala.util.control.ControlThrowable`
   - `scala.util.control.ControlThrowable`
   - all other exceptions

   When more than two exceptions are thrown, the first two are combined and re-thrown as described above, and each successive exception thrown is combined as it is thrown.

7.  object chaining extends ChainingSyntax

   Adds chaining methods `tap` and `pipe` to every type.

   Adds chaining methods `tap` and `pipe` to every type. See ChainingOps.

### Inherited from AnyRef

### Inherited from Any

### Ungrouped