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:

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

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

    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 Futures, 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:

    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

  • BigDecimal
  • BigInt
  • Equiv
  • Fractional
  • Integral
  • LowPriorityEquiv
  • LowPriorityOrderingImplicits
  • Numeric
  • Ordered
  • Ordering
  • PartialOrdering
  • PartiallyOrdered
  • ScalaNumericAnyConversions
  • ScalaNumericConversions
  • 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 math

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.

Source
package.scala
See also

java.lang.Math

Linear Supertypes
Content Hierarchy
Ordering
  1. Grouped
  2. Alphabetic
  3. By Inheritance
Inherited
  1. math
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Type Members

  1. final class BigDecimal extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[BigDecimal]

    BigDecimal represents decimal floating-point numbers of arbitrary precision.

    BigDecimal represents decimal floating-point numbers of arbitrary precision. By default, the precision approximately matches that of IEEE 128-bit floating point numbers (34 decimal digits, HALF_EVEN rounding mode). Within the range of IEEE binary128 numbers, BigDecimal will agree with BigInt for both equality and hash codes (and will agree with primitive types as well). Beyond that range--numbers with more than 4934 digits when written out in full--the hashCode of BigInt and BigDecimal is allowed to diverge due to difficulty in efficiently computing both the decimal representation in BigDecimal and the binary representation in BigInt.

    When creating a BigDecimal from a Double or Float, care must be taken as the binary fraction representation of Double and Float does not easily convert into a decimal representation. Three explicit schemes are available for conversion. BigDecimal.decimal will convert the floating-point number to a decimal text representation, and build a BigDecimal based on that. BigDecimal.binary will expand the binary fraction to the requested or default precision. BigDecimal.exact will expand the binary fraction to the full number of digits, thus producing the exact decimal value corresponding to the binary fraction of that floating-point number. BigDecimal equality matches the decimal expansion of Double: BigDecimal.decimal(0.1) == 0.1. Note that since 0.1f != 0.1, the same is not true for Float. Instead, 0.1f == BigDecimal.decimal((0.1f).toDouble).

    To test whether a BigDecimal number can be converted to a Double or Float and then back without loss of information by using one of these methods, test with isDecimalDouble, isBinaryDouble, or isExactDouble or the corresponding Float versions. Note that BigInt's isValidDouble will agree with isExactDouble, not the isDecimalDouble used by default.

    BigDecimal uses the decimal representation of binary floating-point numbers to determine equality and hash codes. This yields different answers than conversion between Long and Double values, where the exact form is used. As always, since floating-point is a lossy representation, it is advisable to take care when assuming identity will be maintained across multiple conversions.

    BigDecimal maintains a MathContext that determines the rounding that is applied to certain calculations. In most cases, the value of the BigDecimal is also rounded to the precision specified by the MathContext. To create a BigDecimal with a different precision than its MathContext, use new BigDecimal(new java.math.BigDecimal(...), mc). Rounding will be applied on those mathematical operations that can dramatically change the number of digits in a full representation, namely multiplication, division, and powers. The left-hand argument's MathContext always determines the degree of rounding, if any, and is the one propagated through arithmetic operations that do not apply rounding themselves.

  2. final class BigInt extends ScalaNumber with ScalaNumericConversions with Serializable with Ordered[BigInt]

    A type with efficient encoding of arbitrary integers.

    A type with efficient encoding of arbitrary integers.

    It wraps java.math.BigInteger, with optimization for small values that can be encoded in a Long.

  3. trait Equiv[T] extends Serializable

    A trait for representing equivalence relations.

    A trait for representing equivalence relations. It is important to distinguish between a type that can be compared for equality or equivalence and a representation of equivalence on some type. This trait is for representing the latter.

    An equivalence relation is a binary relation on a type. This relation is exposed as the equiv method of the Equiv trait. The relation must be:

    1. reflexive: equiv(x, x) == true for any x of type T.
    2. symmetric: equiv(x, y) == equiv(y, x) for any x and y of type T.
    3. transitive: if equiv(x, y) == true and equiv(y, z) == true, then equiv(x, z) == true for any x, y, and z of type T.
  4. trait Fractional[T] extends Numeric[T]
  5. trait Integral[T] extends Numeric[T]
  6. trait LowPriorityEquiv extends AnyRef
  7. trait LowPriorityOrderingImplicits extends AnyRef
  8. trait Numeric[T] extends Ordering[T]
  9. trait Ordered[A] extends Comparable[A]

    A trait for data that have a single, natural ordering.

    A trait for data that have a single, natural ordering. See scala.math.Ordering before using this trait for more information about whether to use scala.math.Ordering instead.

    Classes that implement this trait can be sorted with scala.util.Sorting and can be compared with standard comparison operators (e.g. > and <).

    Ordered should be used for data with a single, natural ordering (like integers) while Ordering allows for multiple ordering implementations. An Ordering instance will be implicitly created if necessary.

    scala.math.Ordering is an alternative to this trait that allows multiple orderings to be defined for the same type.

    scala.math.PartiallyOrdered is an alternative to this trait for partially ordered data.

    For example, create a simple class that implements Ordered and then sort it with scala.util.Sorting:

    case class OrderedClass(n:Int) extends Ordered[OrderedClass] {
    	def compare(that: OrderedClass) =  this.n - that.n
    }
    
    val x = Array(OrderedClass(1), OrderedClass(5), OrderedClass(3))
    scala.util.Sorting.quickSort(x)
    x

    It is important that the equals method for an instance of Ordered[A] be consistent with the compare method. However, due to limitations inherent in the type erasure semantics, there is no reasonable way to provide a default implementation of equality for instances of Ordered[A]. Therefore, if you need to be able to use equality on an instance of Ordered[A] you must provide it yourself either when inheriting or instantiating.

    It is important that the hashCode method for an instance of Ordered[A] be consistent with the compare method. However, it is not possible to provide a sensible default implementation. Therefore, if you need to be able compute the hash of an instance of Ordered[A] you must provide it yourself either when inheriting or instantiating.

    See also

    scala.math.Ordering, scala.math.PartiallyOrdered

  10. trait Ordering[T] extends Comparator[T] with PartialOrdering[T] with Serializable

    Ordering is a trait whose instances each represent a strategy for sorting instances of a type.

    Ordering is a trait whose instances each represent a strategy for sorting instances of a type.

    Ordering's companion object defines many implicit objects to deal with subtypes of AnyVal (e.g. Int, Double), String, and others.

    To sort instances by one or more member variables, you can take advantage of these built-in orderings using Ordering.by and Ordering.on:

    import scala.util.Sorting
    val pairs = Array(("a", 5, 2), ("c", 3, 1), ("b", 1, 3))
    
    // sort by 2nd element
    Sorting.quickSort(pairs)(Ordering.by[(String, Int, Int), Int](_._2))
    
    // sort by the 3rd element, then 1st
    Sorting.quickSort(pairs)(Ordering[(Int, String)].on(x => (x._3, x._1)))

    An Ordering[T] is implemented by specifying the compare method, compare(a: T, b: T): Int, which decides how to order two instances a and b. Instances of Ordering[T] can be used by things like scala.util.Sorting to sort collections like Array[T].

    For example:

    import scala.util.Sorting
    
    case class Person(name:String, age:Int)
    val people = Array(Person("bob", 30), Person("ann", 32), Person("carl", 19))
    
    // sort by age
    object AgeOrdering extends Ordering[Person] {
      def compare(a:Person, b:Person) = a.age.compare(b.age)
    }
    Sorting.quickSort(people)(AgeOrdering)

    This trait and scala.math.Ordered both provide this same functionality, but in different ways. A type T can be given a single way to order itself by extending Ordered. Using Ordering, this same type may be sorted in many other ways. Ordered and Ordering both provide implicits allowing them to be used interchangeably.

    You can import scala.math.Ordering.Implicits._ to gain access to other implicit orderings.

    Annotations
    @implicitNotFound()
    See also

    scala.math.Ordered, scala.util.Sorting, scala.math.Ordering.Implicits

  11. trait PartialOrdering[T] extends Equiv[T]

    A trait for representing partial orderings.

    A trait for representing partial orderings. It is important to distinguish between a type that has a partial order and a representation of partial ordering on some type. This trait is for representing the latter.

    A partial ordering is a binary relation on a type T, exposed as the lteq method of this trait. This relation must be:

    • reflexive: lteq(x, x) == true, for any x of type T.
    • anti-symmetric: if lteq(x, y) == true and lteq(y, x) == true then equiv(x, y) == true, for any x and y of type T.
    • transitive: if lteq(x, y) == true and lteq(y, z) == true then lteq(x, z) == true, for any x, y, and z of type T.

    Additionally, a partial ordering induces an equivalence relation on a type T: x and y of type T are equivalent if and only if lteq(x, y) && lteq(y, x) == true. This equivalence relation is exposed as the equiv method, inherited from the Equiv trait.

  12. trait PartiallyOrdered[+A] extends Any

    A class for partially ordered data.

  13. trait ScalaNumericAnyConversions extends Any

    Conversions which present a consistent conversion interface across all the numeric types, suitable for use in value classes.

  14. trait ScalaNumericConversions extends ScalaNumber with ScalaNumericAnyConversions

    A slightly more specific conversion trait for classes which extend ScalaNumber (which excludes value classes.)

Value Members

  1. final val E: Double(2.718281828459045)

    The Double value that is closer than any other to e, the base of the natural logarithms.

  2. def IEEEremainder(x: Double, y: Double): Double

  3. final val Pi: Double(3.141592653589793)

    The Double value that is closer than any other to pi, the ratio of the circumference of a circle to its diameter.

  4. def abs(x: Double): Double

  5. def abs(x: Float): Float

  6. def abs(x: Long): Long

  7. def abs(x: Int): Int

  8. def acos(x: Double): Double

  9. def addExact(x: Long, y: Long): Long

  10. def addExact(x: Int, y: Int): Int

  11. def asin(x: Double): Double

  12. def atan(x: Double): Double

  13. def atan2(y: Double, x: Double): Double

    Converts rectangular coordinates (x, y) to polar (r, theta).

    Converts rectangular coordinates (x, y) to polar (r, theta).

    y

    the abscissa coordinate

    x

    the ordinate coordinate

    returns

    the theta component of the point (r, theta) in polar coordinates that corresponds to the point (x, y) in Cartesian coordinates.

  14. def cbrt(x: Double): Double

    Returns the cube root of the given Double value.

    Returns the cube root of the given Double value.

    x

    the number to take the cube root of

    returns

    the value ∛x

  15. def ceil(x: Double): Double

  16. def copySign(magnitude: Float, sign: Float): Float

  17. def copySign(magnitude: Double, sign: Double): Double

  18. def cos(x: Double): Double

  19. def cosh(x: Double): Double

    Returns the hyperbolic cosine of the given Double value.

  20. def decrementExact(x: Long): Long

  21. def decrementExact(x: Int): Int

  22. def exp(x: Double): Double

    Returns Euler's number e raised to the power of a Double value.

    Returns Euler's number e raised to the power of a Double value.

    x

    the exponent to raise e to.

    returns

    the value ea, where e is the base of the natural logarithms.

  23. def expm1(x: Double): Double

    Returns exp(x) - 1.

  24. def floor(x: Double): Double

  25. def floorDiv(x: Long, y: Long): Long

  26. def floorDiv(x: Int, y: Int): Int

  27. def floorMod(x: Long, y: Long): Long

  28. def floorMod(x: Int, y: Int): Int

  29. def getExponent(d: Double): Int

  30. def getExponent(f: Float): Int

  31. def hypot(x: Double, y: Double): Double

    Returns the square root of the sum of the squares of both given Double values without intermediate underflow or overflow.

    Returns the square root of the sum of the squares of both given Double values without intermediate underflow or overflow.

    The r component of the point (r, theta) in polar coordinates that corresponds to the point (x, y) in Cartesian coordinates.

  32. def incrementExact(x: Long): Long

  33. def incrementExact(x: Int): Int

  34. def log(x: Double): Double

    Returns the natural logarithm of a Double value.

    Returns the natural logarithm of a Double value.

    x

    the number to take the natural logarithm of

    returns

    the value logₑ(x) where e is Eulers number

  35. def log10(x: Double): Double

    Returns the base 10 logarithm of the given Double value.

  36. def log1p(x: Double): Double

    Returns the natural logarithm of the sum of the given Double value and 1.

  37. def max(x: Double, y: Double): Double

  38. def max(x: Float, y: Float): Float

  39. def max(x: Long, y: Long): Long

  40. def max(x: Int, y: Int): Int

  41. def min(x: Double, y: Double): Double

  42. def min(x: Float, y: Float): Float

  43. def min(x: Long, y: Long): Long

  44. def min(x: Int, y: Int): Int

  45. def multiplyExact(x: Long, y: Long): Long

  46. def multiplyExact(x: Int, y: Int): Int

  47. def negateExact(x: Long): Long

  48. def negateExact(x: Int): Int

  49. def nextAfter(start: Float, direction: Double): Float

  50. def nextAfter(start: Double, direction: Double): Double

  51. def nextDown(f: Float): Float

  52. def nextDown(d: Double): Double

  53. def nextUp(f: Float): Float

  54. def nextUp(d: Double): Double

  55. def pow(x: Double, y: Double): Double

    Returns the value of the first argument raised to the power of the second argument.

    Returns the value of the first argument raised to the power of the second argument.

    x

    the base.

    y

    the exponent.

    returns

    the value xy.

  56. def random(): Double

    Returns a Double value with a positive sign, greater than or equal to 0.0 and less than 1.0.

  57. def rint(x: Double): Double

    Returns the Double value that is closest in value to the argument and is equal to a mathematical integer.

    Returns the Double value that is closest in value to the argument and is equal to a mathematical integer.

    x

    a Double value

    returns

    the closest floating-point value to a that is equal to a mathematical integer.

  58. def round(x: Double): Long

    Returns the closest Long to the argument.

    Returns the closest Long to the argument.

    x

    a floating-point value to be rounded to a Long.

    returns

    the value of the argument rounded to the nearestlong value.

  59. def round(x: Float): Int

    Returns the closest Int to the argument.

    Returns the closest Int to the argument.

    x

    a floating-point value to be rounded to a Int.

    returns

    the value of the argument rounded to the nearest Int value.

  60. def scalb(f: Float, scaleFactor: Int): Float

  61. def scalb(d: Double, scaleFactor: Int): Double

  62. def signum(x: Double): Double

  63. def signum(x: Float): Float

  64. def signum(x: Long): Long

    Note

    Forwards to java.lang.Long

  65. def signum(x: Int): Int

    Note

    Forwards to java.lang.Integer

  66. def sin(x: Double): Double

  67. def sinh(x: Double): Double

    Returns the hyperbolic sine of the given Double value.

  68. def sqrt(x: Double): Double

    Returns the square root of a Double value.

    Returns the square root of a Double value.

    x

    the number to take the square root of

    returns

    the value √x

  69. def subtractExact(x: Long, y: Long): Long

  70. def subtractExact(x: Int, y: Int): Int

  71. def tan(x: Double): Double

  72. def tanh(x: Double): Double

    Returns the hyperbolic tangent of the given Double value.

  73. def toDegrees(x: Double): Double

    Converts an angle measured in radians to an approximately equivalent angle measured in degrees.

    Converts an angle measured in radians to an approximately equivalent angle measured in degrees.

    x

    angle, in radians

    returns

    the measurement of the angle x in degrees.

  74. def toIntExact(x: Long): Int

  75. def toRadians(x: Double): Double

    Converts an angle measured in degrees to an approximately equivalent angle measured in radians.

    Converts an angle measured in degrees to an approximately equivalent angle measured in radians.

    x

    an angle, in degrees

    returns

    the measurement of the angle x in radians.

  76. def ulp(x: Float): Float

    Returns the size of an ulp of the given Float value.

  77. def ulp(x: Double): Double

    Returns the size of an ulp of the given Double value.

  78. object BigDecimal extends java.io.Serializable
  79. object BigInt extends java.io.Serializable
  80. object Equiv extends LowPriorityEquiv with java.io.Serializable
  81. object Fractional extends java.io.Serializable
  82. object Integral extends java.io.Serializable
  83. object Numeric extends java.io.Serializable
  84. object Ordered
  85. object Ordering extends LowPriorityOrderingImplicits with java.io.Serializable

    This is the companion object for the scala.math.Ordering trait.

    This is the companion object for the scala.math.Ordering trait.

    It contains many implicit orderings as well as well as methods to construct new orderings.

  86. object PartialOrdering extends java.io.Serializable

Deprecated Value Members

  1. def round(x: Long): Long

    There is no reason to round a Long, but this method prevents unintended conversion to Float followed by rounding to Int.

    There is no reason to round a Long, but this method prevents unintended conversion to Float followed by rounding to Int.

    Annotations
    @deprecated
    Deprecated

    (Since version 2.11.0) This is an integer type; there is no reason to round it. Perhaps you meant to call this with a floating-point value?

    Note

    Does not forward to java.lang.Math

Inherited from AnyRef

Inherited from Any

Mathematical Constants

Minimum and Maximum

Find the min or max of two numbers. Note: scala.collection.IterableOnceOps has min and max methods which determine the min or max of a collection.

Rounding

Scaling

Scaling with rounding guarantees

Exponential and Logarithmic

Trigonometric

Arguments in radians

Angular Measurement Conversion

Hyperbolic

Absolute Values

Determine the magnitude of a value by discarding the sign. Results are >= 0.

Signs

For signum extract the sign of a value. Results are -1, 0 or 1. Note the signum methods are not pure forwarders to the Java versions. In particular, the return type of java.lang.Long.signum is Int, but here it is widened to Long so that each overloaded variant will return the same numeric type it is passed.

Root Extraction

Polar Coordinates

Unit of Least Precision

Pseudo Random Number Generation

Exact Arithmetic

Integral addition, multiplication, stepping and conversion throwing ArithmeticException instead of underflowing or overflowing

Modulus and Quotient

Calculate quotient values by rounding to negative infinity

Adjacent Floats

Ungrouped