An instance of A <:< B witnesses that A is a subtype of B. Requiring an implicit argument of the type A <:< B encodes the generalized constraint A <: B.

To constrain any abstract type T that's in scope in a method's argument list (not just the method's own type parameters) simply add an implicit argument of type T <:< U, where U is the required upper bound; or for lower-bounds, use: L <:< T, where L is the required lower bound.

In case of any confusion over which method goes in what direction, all the "Co" methods (including apply) go from left to right in the type ("with" the type), and all the "Contra" methods go from right to left ("against" the type). E.g., apply turns a From into a To, and substituteContra replaces the Tos in a type with Froms.

In part contributed by Jason Zaugg.

An instance of A =:= B witnesses that the types A and B are equal. It also acts as a A <:< B, but not a B <:< A (directly) due to restrictions on subclassing.

In case of any confusion over which method goes in what direction, all the "Co" methods (including apply) go from left to right in the type ("with" the type), and all the "Contra" methods go from right to left ("against" the type). E.g., apply turns a From into a To, and substituteContra replaces the Tos in a type with Froms.

Class Any is the root of the Scala class hierarchy. Every class in a Scala execution environment inherits directly or indirectly from this class.

Starting with Scala 2.10 it is possible to directly extend Any using universal traits. A universal trait is a trait that extends Any, only has defs as members, and does no initialization.

The main use case for universal traits is to allow basic inheritance of methods for value classes. For example,

trait Printable extends Any {
  def print(): Unit = println(this)
}
class Wrapper(val underlying: Int) extends AnyVal with Printable

val w = new Wrapper(3)
w.print()

See the Value Classes and Universal Traits for more details on the interplay of universal traits and value classes.

AnyVal is the root class of all value types, which describe values not implemented as objects in the underlying host system. Value classes are specified in Scala Language Specification, section 12.2.

The standard implementation includes nine AnyVal subtypes:

scala.Double, scala.Float, scala.Long, scala.Int, scala.Char, scala.Short, and scala.Byte are the numeric value types.

scala.Unit and scala.Boolean are the non-numeric value types.

Other groupings:

• The subrange types are scala.Byte, scala.Short, and scala.Char.
• The integer types include the subrange types as well as scala.Int and scala.Long.
• The floating point types are scala.Float and scala.Double.

Prior to Scala 2.10, AnyVal was a sealed trait. Beginning with Scala 2.10, however, it is possible to define a subclass of AnyVal called a user-defined value class which is treated specially by the compiler. Properly-defined user value classes provide a way to improve performance on user-defined types by avoiding object allocation at runtime, and by replacing virtual method invocations with static method invocations.

User-defined value classes which avoid object allocation...

• must have a single val parameter that is the underlying runtime representation.
• can define defs, but no vals, vars, or nested traits, classes or objects.
• typically extend no other trait apart from AnyVal.
• cannot be used in type tests or pattern matching.
• may not override equals or hashCode methods.

A minimal example:

class Wrapper(val underlying: Int) extends AnyVal {
  def foo: Wrapper = new Wrapper(underlying * 19)
}

It's important to note that user-defined value classes are limited, and in some circumstances, still must allocate a value class instance at runtime. These limitations and circumstances are explained in greater detail in the Value Classes and Universal Traits.

The App trait can be used to quickly turn objects into executable programs. Here is an example:

object Main extends App {
  Console.println("Hello World: " + (args mkString ", "))
}

No explicit main method is needed. Instead, the whole class body becomes the “main method”.

args returns the current command line arguments as an array.

Caveats

It should be noted that this trait is implemented using the DelayedInit functionality, which means that fields of the object will not have been initialized before the main method has been executed.

Future versions of this trait will no longer extend DelayedInit.

In Scala 3, the DelayedInit feature was dropped. App exists only in a limited form that also does not support command line arguments and will be deprecated in the future.

@main methods are the recommended scheme to generate programs that can be invoked from the command line in Scala 3.

@main def runMyProgram(args: String*): Unit = {
  // your program here
}

If programs need to cross-build between Scala 2 and Scala 3, it is recommended to use an explicit main method:

object Main {
  def main(args: Array[String]): Unit = {
    // your program here
  }
}

Arrays are mutable, indexed collections of values. Array[T] is Scala's representation for Java's T[].

val numbers = Array(1, 2, 3, 4)
val first = numbers(0) // read the first element
numbers(3) = 100 // replace the 4th array element with 100
val biggerNumbers = numbers.map(_ * 2) // multiply all numbers by two

Arrays make use of two common pieces of Scala syntactic sugar, shown on lines 2 and 3 of the above example code. Line 2 is translated into a call to apply(Int), while line 3 is translated into a call to update(Int, T).

Two implicit conversions exist in scala.Predef that are frequently applied to arrays: a conversion to scala.collection.ArrayOps (shown on line 4 of the example above) and a conversion to scala.collection.mutable.ArraySeq (a subtype of scala.collection.Seq). Both types make available many of the standard operations found in the Scala collections API. The conversion to ArrayOps is temporary, as all operations defined on ArrayOps return an Array, while the conversion to ArraySeq is permanent as all operations return a ArraySeq.

The conversion to ArrayOps takes priority over the conversion to ArraySeq. For instance, consider the following code:

val arr = Array(1, 2, 3)
val arrReversed = arr.reverse
val seqReversed : collection.Seq[Int] = arr.reverse

Value arrReversed will be of type Array[Int], with an implicit conversion to ArrayOps occurring to perform the reverse operation. The value of seqReversed, on the other hand, will be computed by converting to ArraySeq first and invoking the variant of reverse that returns another ArraySeq.

Boolean (equivalent to Java's boolean primitive type) is a subtype of scala.AnyVal. Instances of Boolean are not represented by an object in the underlying runtime system.

There is an implicit conversion from scala.Boolean => scala.runtime.RichBoolean which provides useful non-primitive operations.

Byte, a 8-bit signed integer (equivalent to Java's byte primitive type) is a subtype of scala.AnyVal. Instances of Byte are not represented by an object in the underlying runtime system.

There is an implicit conversion from scala.Byte => scala.runtime.RichByte which provides useful non-primitive operations.

Char, a 16-bit unsigned integer (equivalent to Java's char primitive type) is a subtype of scala.AnyVal. Instances of Char are not represented by an object in the underlying runtime system.

There is an implicit conversion from scala.Char => scala.runtime.RichChar which provides useful non-primitive operations.

Double, a 64-bit IEEE-754 floating point number (equivalent to Java's double primitive type) is a subtype of scala.AnyVal. Instances of Double are not represented by an object in the underlying runtime system.

There is an implicit conversion from scala.Double => scala.runtime.RichDouble which provides useful non-primitive operations.

A marker trait that enables dynamic invocations. Instances x of this trait allow method invocations x.meth(args) for arbitrary method names meth and argument lists args as well as field accesses x.field for arbitrary field names field.

If a call is not natively supported by x (i.e. if type checking fails), it is rewritten according to the following rules:

foo.method("blah")      ~~> foo.applyDynamic("method")("blah")
foo.method(x = "blah")  ~~> foo.applyDynamicNamed("method")(("x", "blah"))
foo.method(x = 1, 2)    ~~> foo.applyDynamicNamed("method")(("x", 1), ("", 2))
foo.field           ~~> foo.selectDynamic("field")
foo.varia = 10      ~~> foo.updateDynamic("varia")(10)
foo.arr(10) = 13    ~~> foo.selectDynamic("arr").update(10, 13)
foo.arr(10)         ~~> foo.applyDynamic("arr")(10)

As of Scala 2.10, defining direct or indirect subclasses of this trait is only possible if the language feature dynamics is enabled.

Defines a finite set of values specific to the enumeration. Typically these values enumerate all possible forms something can take and provide a lightweight alternative to case classes.

Each call to a Value method adds a new unique value to the enumeration. To be accessible, these values are usually defined as val members of the enumeration.

All values in an enumeration share a common, unique type defined as the Value type member of the enumeration (Value selected on the stable identifier path of the enumeration instance).

Values SHOULD NOT be added to an enumeration after its construction; doing so makes the enumeration thread-unsafe. If values are added to an enumeration from multiple threads (in a non-synchronized fashion) after construction, the behavior of the enumeration is undefined.

An interface containing operations for equality. The only method not already present in class AnyRef is canEqual.

Float, a 32-bit IEEE-754 floating point number (equivalent to Java's float primitive type) is a subtype of scala.AnyVal. Instances of Float are not represented by an object in the underlying runtime system.

There is an implicit conversion from scala.Float => scala.runtime.RichFloat which provides useful non-primitive operations.

A function of 0 parameters.

In the following example, the definition of greeting is shorthand, conceptually, for the anonymous class definition anonfun0, although the implementation details of how the function value is constructed may differ:

 object Main extends App {
   val name = "world"
   val greeting = () => s"hello, $name"

   val anonfun0 = new Function0[String] {
     def apply(): String = s"hello, $name"
   }
   assert(greeting() == anonfun0())
}

A function of 1 parameter.

In the following example, the definition of succ is shorthand, conceptually, for the anonymous class definition anonfun1, although the implementation details of how the function value is constructed may differ:

 object Main extends App {
   val succ = (x: Int) => x + 1
   val anonfun1 = new Function1[Int, Int] {
     def apply(x: Int): Int = x + 1
   }
   assert(succ(0) == anonfun1(0))
}

Note that the difference between Function1 and scala.PartialFunction is that the latter can specify inputs which it will not handle.

A function of 2 parameters.

In the following example, the definition of max is shorthand, conceptually, for the anonymous class definition anonfun2, although the implementation details of how the function value is constructed may differ:

 object Main extends App {
   val max = (x: Int, y: Int) => if (x < y) y else x

   val anonfun2 = new Function2[Int, Int, Int] {
     def apply(x: Int, y: Int): Int = if (x < y) y else x
   }
   assert(max(0, 1) == anonfun2(0, 1))
}

Int, a 32-bit signed integer (equivalent to Java's int primitive type) is a subtype of scala.AnyVal. Instances of Int are not represented by an object in the underlying runtime system.

There is an implicit conversion from scala.Int => scala.runtime.RichInt which provides useful non-primitive operations.

Long, a 64-bit signed integer (equivalent to Java's long primitive type) is a subtype of scala.AnyVal. Instances of Long are not represented by an object in the underlying runtime system.

There is an implicit conversion from scala.Long => scala.runtime.RichLong which provides useful non-primitive operations.

Throwing this exception can be a temporary replacement for a method body that remains to be implemented. For instance, the exception is thrown by Predef.???.

Nothing is - together with scala.Null - at the bottom of Scala's type hierarchy.

Nothing is a subtype of every other type (including scala.Null); there exist no instances of this type. Although type Nothing is uninhabited, it is nevertheless useful in several ways. For instance, the Scala library defines a value scala.collection.immutable.Nil of type List[Nothing]. Because lists are covariant in Scala, this makes scala.collection.immutable.Nil an instance of List[T], for any element of type T.

Another usage for Nothing is the return type for methods which never return normally. One example is method error in scala.sys, which always throws an exception.

Null is - together with scala.Nothing - at the bottom of the Scala type hierarchy.

Null is the type of the null literal. It is a subtype of every type except those of value classes. Value classes are subclasses of AnyVal, which includes primitive types such as Int, Boolean, and user-defined value classes.

Since Null is not a subtype of value types, null is not a member of any such type. For instance, it is not possible to assign null to a variable of type scala.Int.

Represents optional values. Instances of Option are either an instance of scala.Some or the object None.

The most idiomatic way to use an scala.Option instance is to treat it as a collection or monad and use map,flatMap, filter, or foreach:

val name: Option[String] = request getParameter "name"
val upper = name map { _.trim } filter { _.length != 0 } map { _.toUpperCase }
println(upper getOrElse "")

Note that this is equivalent to

val upper = for {
  name <- request getParameter "name"
  trimmed <- Some(name.trim)
  upper <- Some(trimmed.toUpperCase) if trimmed.length != 0
} yield upper
println(upper getOrElse "")

Because of how for comprehension works, if None is returned from request.getParameter, the entire expression results in None

This allows for sophisticated chaining of scala.Option values without having to check for the existence of a value.

These are useful methods that exist for both scala.Some and None.

• isDefined — True if not empty
• isEmpty — True if empty
• nonEmpty — True if not empty
• orElse — Evaluate and return alternate optional value if empty
• getOrElse — Evaluate and return alternate value if empty
• get — Return value, throw exception if empty
• fold — Apply function on optional value, return default if empty
• map — Apply a function on the optional value
• flatMap — Same as map but function must return an optional value
• foreach — Apply a procedure on option value
• collect — Apply partial pattern match on optional value
• filter — An optional value satisfies predicate
• filterNot — An optional value doesn't satisfy predicate
• exists — Apply predicate on optional value, or false if empty
• forall — Apply predicate on optional value, or true if empty
• contains — Checks if value equals optional value, or false if empty
• zip — Combine two optional values to make a paired optional value
• unzip — Split an optional pair to two optional values
• unzip3 — Split an optional triple to three optional values
• toList — Unary list of optional value, otherwise the empty list

A less-idiomatic way to use scala.Option values is via pattern matching:

val nameMaybe = request getParameter "name"
nameMaybe match {
  case Some(name) =>
    println(name.trim.toUppercase)
  case None =>
    println("No name value")
}

Interacting with code that can occasionally return null can be safely wrapped in scala.Option to become None and scala.Some otherwise.

val abc = new java.util.HashMap[Int, String]
abc.put(1, "A")
bMaybe = Option(abc.get(2))
bMaybe match {
  case Some(b) =>
    println(s"Found $b")
  case None =>
    println("Not found")
}

A partial function of type PartialFunction[A, B] is a unary function where the domain does not necessarily include all values of type A. The function isDefinedAt allows to test dynamically if a value is in the domain of the function.

Even if isDefinedAt returns true for an a: A, calling apply(a) may still throw an exception, so the following code is legal:

val f: PartialFunction[Int, Any] = { case x => x / 0 }   // ArithmeticException: / by zero

It is the responsibility of the caller to call isDefinedAt before calling apply, because if isDefinedAt is false, it is not guaranteed apply will throw an exception to indicate an error condition. If an exception is not thrown, evaluation may result in an arbitrary value.

The usual way to respect this contract is to call applyOrElse, which is expected to be more efficient than calling both isDefinedAt and apply.

The main distinction between PartialFunction and scala.Function1 is that the user of a PartialFunction may choose to do something different with input that is declared to be outside its domain. For example:

val sample = 1 to 10
def isEven(n: Int) = n % 2 == 0
val eveningNews: PartialFunction[Int, String] = {
  case x if isEven(x) => s"$x is even"
}

// The method collect is described as "filter + map"
// because it uses a PartialFunction to select elements
// to which the function is applied.
val evenNumbers = sample.collect(eveningNews)

val oddlyEnough: PartialFunction[Int, String] = {
  case x if !isEven(x) => s"$x is odd"
}

// The method orElse allows chaining another PartialFunction
// to handle input outside the declared domain.
val numbers = sample.map(eveningNews orElse oddlyEnough)

// same as
val numbers = sample.map(n => eveningNews.applyOrElse(n, oddlyEnough))

val half: PartialFunction[Int, Int] = {
  case x if isEven(x) => x / 2
}

// Calculating the domain of a composition can be expensive.
val oddByHalf = half.andThen(oddlyEnough)

// Invokes `half.apply` on even elements!
val oddBalls = sample.filter(oddByHalf.isDefinedAt)

// Better than filter(oddByHalf.isDefinedAt).map(oddByHalf)
val oddBalls = sample.collect(oddByHalf)

// Providing "default" values.
val oddsAndEnds = sample.map(n => oddByHalf.applyOrElse(n, (i: Int) => s"[$i]"))

Base trait for all products, which in the standard library include at least scala.Product1 through scala.Product22 and therefore also their subclasses scala.Tuple1 through scala.Tuple22. In addition, all case classes implement Product with synthetically generated methods.

Annotation for specifying the serialVersionUID field of a (serializable) class.

On the JVM, a class with this annotation will receive a private, static, and final field called serialVersionUID with the provided value, which the JVM's serialization mechanism uses to determine serialization compatibility between different versions of a class.

Short, a 16-bit signed integer (equivalent to Java's short primitive type) is a subtype of scala.AnyVal. Instances of Short are not represented by an object in the underlying runtime system.

There is an implicit conversion from scala.Short => scala.runtime.RichShort which provides useful non-primitive operations.

Singleton is used by the compiler as a supertype for singleton types. This includes literal types, as they are also singleton types.

scala> object A { val x = 42 }
defined object A

scala> implicitly[A.type <:< Singleton]
res12: A.type <:< Singleton = generalized constraint

scala> implicitly[A.x.type <:< Singleton]
res13: A.x.type <:< Singleton = generalized constraint

scala> implicitly[42 <:< Singleton]
res14: 42 <:< Singleton = generalized constraint

scala> implicitly[Int <:< Singleton]
^
error: Cannot prove that Int <:< Singleton.

Singleton has a special meaning when it appears as an upper bound on a formal type parameter. Normally, type inference in Scala widens singleton types to the underlying non-singleton type. When a type parameter has an explicit upper bound of Singleton, the compiler infers a singleton type.

scala> def check42[T](x: T)(implicit ev: T =:= 42): T = x
check42: [T](x: T)(implicit ev: T =:= 42)T

scala> val x1 = check42(42)
^
error: Cannot prove that Int =:= 42.

scala> def singleCheck42[T <: Singleton](x: T)(implicit ev: T =:= 42): T = x
singleCheck42: [T <: Singleton](x: T)(implicit ev: T =:= 42)T

scala> val x2 = singleCheck42(42)
x2: Int = 42

See also SIP-23 about Literal-based Singleton Types.

Class Some[A] represents existing values of type A.

A common supertype for companions of specializable types. Should not be extended in user code.

This class provides the basic mechanism to do String Interpolation. String Interpolation allows users to embed variable references directly in *processed* string literals. Here's an example:

val name = "James"
println(s"Hello, $name")  // Hello, James

Any processed string literal is rewritten as an instantiation and method call against this class. For example:

s"Hello, $name"

is rewritten to be:

StringContext("Hello, ", "").s(name)

By default, this class provides the raw, s and f methods as available interpolators.

To provide your own string interpolator, create an implicit class which adds a method to StringContext. Here's an example:

implicit class JsonHelper(private val sc: StringContext) extends AnyVal {
  def json(args: Any*): JSONObject = ...
}
val x: JSONObject = json"{ a: $a }"

Here the JsonHelper extension class implicitly adds the json method to StringContext which can be used for json string literals.

This class provides a simple way to get unique objects for equal strings. Since symbols are interned, they can be compared using reference equality.

A tuple of 1 elements; the canonical representation of a scala.Product1.

A tuple of 10 elements; the canonical representation of a scala.Product10.

A tuple of 11 elements; the canonical representation of a scala.Product11.

A tuple of 12 elements; the canonical representation of a scala.Product12.

A tuple of 13 elements; the canonical representation of a scala.Product13.

A tuple of 14 elements; the canonical representation of a scala.Product14.

A tuple of 15 elements; the canonical representation of a scala.Product15.

A tuple of 16 elements; the canonical representation of a scala.Product16.

A tuple of 17 elements; the canonical representation of a scala.Product17.

A tuple of 18 elements; the canonical representation of a scala.Product18.

A tuple of 19 elements; the canonical representation of a scala.Product19.

A tuple of 2 elements; the canonical representation of a scala.Product2.

A tuple of 20 elements; the canonical representation of a scala.Product20.

A tuple of 21 elements; the canonical representation of a scala.Product21.

A tuple of 22 elements; the canonical representation of a scala.Product22.

A tuple of 3 elements; the canonical representation of a scala.Product3.

A tuple of 4 elements; the canonical representation of a scala.Product4.

A tuple of 5 elements; the canonical representation of a scala.Product5.

A tuple of 6 elements; the canonical representation of a scala.Product6.

A tuple of 7 elements; the canonical representation of a scala.Product7.

A tuple of 8 elements; the canonical representation of a scala.Product8.

A tuple of 9 elements; the canonical representation of a scala.Product9.

This class implements errors which are thrown whenever a field is used before it has been initialized.

Such runtime checks are not emitted by default. They can be enabled by the -Xcheckinit compiler option.

Unit is a subtype of scala.AnyVal. There is only one value of type Unit, (), and it is not represented by any object in the underlying runtime system. A method with return type Unit is analogous to a Java method which is declared void.

ValueOf[T] provides the unique value of the type T where T is a type which has a single inhabitant. Eligible types are singleton types of the form stablePath.type, Unit and singleton types corresponding to value literals.

The value itself can conveniently be retrieved with Predef#valueOf, which requires a ValueOf to be available in implicit scope.

The compiler provides instances of ValueOf[T] for all eligible types. Typically an instance would be required where a runtime value corresponding to a type level computation is needed.

For example, we might define a type Residue[M <: Int] corresponding to the group of integers modulo M. We could then mandate that residues can be summed only when they are parameterized by the same modulus,

case class Residue[M <: Int](n: Int) extends AnyVal {
  def +(rhs: Residue[M])(implicit m: ValueOf[M]): Residue[M] =
    Residue((this.n + rhs.n) % valueOf[M])
}

val fiveModTen = Residue[10](5)
val nineModTen = Residue[10](9)

fiveModTen + nineModTen    // OK == Residue[10](4)

val fourModEleven = Residue[11](4)

fiveModTen + fourModEleven // compiler error: type mismatch;
                           //   found   : Residue[11]
                           //   required: Residue[10]

Notice that here the modulus is encoded in the type of the values and so does not incur any additional per-value storage cost. When a runtime value of the modulus is required in the implementation of + it is provided at the call site via the implicit argument m of type ValueOf[M].

An annotation that designates that a definition is deprecated. A deprecation warning is issued upon usage of the annotated definition.

Library authors should state the library's deprecation policy in their documentation to give developers guidance on how long a deprecated definition will be preserved.

Library authors should prepend the name of their library to the version number to help developers distinguish deprecations coming from different libraries:

@deprecated("this method will be removed", "FooLib 12.0")
def oldMethod(x: Int) = ...

The compiler will emit deprecation warnings grouped by library and version:

oldMethod(1)
oldMethod(2)
aDeprecatedMethodFromLibraryBar(3, 4)

// warning: there was one deprecation warning (since BarLib 3.2)
// warning: there were two deprecation warnings (since FooLib 12.0)
// warning: there were three deprecation warnings in total; re-run with -deprecation for details

The Scala compiler also warns about using definitions annotated with java.lang.Deprecated. However it is recommended to use the Scala @deprecated annotation in Scala code because it allows providing a deprecation message.

@deprecated in the Scala language and its standard library

A deprecated element of the Scala language or a definition in the Scala standard library will be preserved at least for the current major version.

This means that an element deprecated in some 2.13.x release will be preserved in all 2.13.x releases, but may be removed in the future. (A deprecated element might be kept longer to ease migration, but developers should not rely on this.)

An annotation that designates that inheriting from a class is deprecated.

This is usually done to warn about a non-final class being made final in a future version. Sub-classing such a class then generates a warning.

No warnings are generated if the subclass is in the same compilation unit.

Library authors should state the library's deprecation policy in their documentation to give developers guidance on when a type annotated with @deprecatedInheritance will be finalized.

Library authors should prepend the name of their library to the version number to help developers distinguish deprecations coming from different libraries:

@deprecatedInheritance("this class will be made final", "FooLib 12.0")
class Foo

val foo = new Foo     // no deprecation warning
class Bar extends Foo
// warning: inheritance from class Foo is deprecated (since FooLib 12.0): this class will be made final
// class Bar extends Foo
//                   ^

An annotation that designates that the name of a parameter is deprecated.

Using this name in a named argument generates a deprecation warning.

If the name is omitted, then using the canonical name is deprecated. In that case, lints such as -Xlint:named-booleans which encourage the use of a name will not warn.

Library authors should state the library's deprecation policy in their documentation to give developers guidance on how long a deprecated name will be preserved.

Library authors should prepend the name of their library to the version number to help developers distinguish deprecations coming from different libraries:

def inc(x: Int, @deprecatedName("y", "FooLib 12.0") n: Int): Int = x + n
inc(1, y = 2)

will produce the following warning:

warning: the parameter name y is deprecated (since FooLib 12.0): use n instead
inc(1, y = 2)
         ^

An annotation that designates that overriding a member is deprecated.

Overriding such a member in a sub-class then generates a warning.

Library authors should state the library's deprecation policy in their documentation to give developers guidance on when a method annotated with @deprecatedOverriding will be finalized.

Library authors should prepend the name of their library to the version number to help developers distinguish deprecations coming from different libraries:

class Foo {
  @deprecatedOverriding("this method will be made final", "FooLib 12.0")
  def add(x: Int, y: Int) = x + y
}

class Bar extends Foo // no deprecation warning
class Baz extends Foo {
  override def add(x: Int, y: Int) = x - y
}
// warning: overriding method add in class Foo is deprecated (since FooLib 12.0): this method will be made final
// override def add(x: Int, y: Int) = x - y
//              ^

An annotation for methods that the optimizer should inline.

Note that by default, the Scala optimizer is disabled and no callsites are inlined. See -opt:help and the overview document for information on how to enable the optimizer and inliner.

When inlining is enabled, the inliner will always try to inline methods or callsites annotated @inline (under the condition that inlining from the defining class is allowed). If inlining is not possible, for example because the method is not final, an optimizer warning will be issued. See -Wopt:help for details.

Examples:

@inline   final def f1(x: Int) = x
@noinline final def f2(x: Int) = x
          final def f3(x: Int) = x

 def t1 = f1(1)              // inlined if possible
 def t2 = f2(1)              // not inlined
 def t3 = f3(1)              // may be inlined (the inliner heuristics can select the callsite)
 def t4 = f1(1): @noinline   // not inlined (override at callsite)
 def t5 = f2(1): @inline     // inlined if possible (override at callsite)
 def t6 = f3(1): @inline     // inlined if possible
 def t7 = f3(1): @noinline   // not inlined
}

Note: parentheses are required when annotating a callsite within a larger expression.

def t1 = f1(1) + f1(1): @noinline   // equivalent to (f1(1) + f1(1)): @noinline
def t2 = f1(1) + (f1(1): @noinline) // the second call to f1 is not inlined

Marker for native methods.

@native def f(x: Int, y: List[Long]): String = ...

A @native method is compiled to the platform's native method, while discarding the method's body (if any). The body will be type checked if present.

A method marked @native must be a member of a class, not a trait (since 2.12).

An annotation for methods that the optimizer should not inline.

Note that by default, the Scala optimizer is disabled and no callsites are inlined. See -opt:help for information how to enable the optimizer and inliner.

When inlining is enabled, the inliner will never inline methods or callsites annotated @noinline.

Examples:

@inline   final def f1(x: Int) = x
@noinline final def f2(x: Int) = x
          final def f3(x: Int) = x

 def t1 = f1(1)              // inlined if possible
 def t2 = f2(1)              // not inlined
 def t3 = f3(1)              // may be inlined (the inliner heuristics can select the callsite)
 def t4 = f1(1): @noinline   // not inlined (override at callsite)
 def t5 = f2(1): @inline     // inlined if possible (override at callsite)
 def t6 = f3(1): @inline     // inlined if possible
 def t7 = f3(1): @noinline   // not inlined
}

Note: parentheses are required when annotating a callsite within a larger expression.

def t1 = f1(1) + f1(1): @noinline   // equivalent to (f1(1) + f1(1)): @noinline
def t2 = f1(1) + (f1(1): @noinline) // the second call to f1 is not inlined

Annotate type parameters on which code should be automatically specialized. For example:

class MyList[@specialized T] ...

Type T can be specialized on a subset of the primitive types by specifying a list of primitive types to specialize at:

class MyList[@specialized(Int, Double, Boolean) T] ..

Annotation for specifying the exceptions thrown by a method. For example:

class Reader(fname: String) {
  private val in = new BufferedReader(new FileReader(fname))
  @throws[IOException]("if the file doesn't exist")
  def read() = in.read()
}

An annotation to designate that the annotated entity should not be considered for additional compiler checks. Specific applications include annotating the subject of a match expression to suppress exhaustiveness and reachability warnings, and annotating a type argument in a match case to suppress unchecked warnings.

Such suppression should be used with caution, without which one may encounter scala.MatchError or java.lang.ClassCastException at runtime. In most cases one can and should address the warning instead of suppressing it.

object Test extends App {
  // This would normally warn "match is not exhaustive"
  // because `None` is not covered.
  def f(x: Option[String]) = (x: @unchecked) match { case Some(y) => y }
  // This would normally warn "type pattern is unchecked"
  // but here will blindly cast the head element to String.
  def g(xs: Any) = xs match { case x: List[String @unchecked] => x.head }
}

Classes and objects (but note, not traits) inheriting the DelayedInit marker trait will have their initialization code rewritten as follows: code becomes delayedInit(code).

Initialization code comprises all statements and all value definitions that are executed during initialization.

Example:

trait Helper extends DelayedInit {
  def delayedInit(body: => Unit) = {
    println("dummy text, printed before initialization of C")
    body // evaluates the initialization code of C
  }
}

class C extends Helper {
  println("this is the initialization code of C")
}

object Test extends App {
  val c = new C
}

Should result in the following being printed:

dummy text, printed before initialization of C
this is the initialization code of C

This class implements a simple proxy that forwards all calls to the public, non-final methods defined in class Any to another object self. Those methods are:

def hashCode(): Int
def equals(other: Any): Boolean
def toString(): String

Note: forwarding methods in this way will most likely create an asymmetric equals method, which is not generally recommended.