Singleton Types

SimpleType  ::=  Path ‘.’ ‘type’

A singleton type is of the form $p.$type. Where $p$ is a path pointing to a value which conforms to scala.AnyRef, the type denotes the set of values consisting of null and the value denoted by $p$ (i.e., the value $v$ for which v eq p). Where the path does not conform to scala.AnyRef the type denotes the set consisting of only the value denoted by $p$.

Literal Types

SimpleType  ::=  Literal

A literal type lit is a special kind of singleton type which denotes the single literal value lit. Thus, the type ascription 1: 1 gives the most precise type to the literal value 1: the literal type 1.

At run time, an expression e is considered to have literal type lit if e == lit. Concretely, the result of e.isInstanceOf[lit] and e match { case _ : lit => } is determined by evaluating e == lit.

Literal types are available for all types for which there is dedicated syntax, except Unit. This includes the numeric types (other than Byte and Short which don't currently have syntax), Boolean, Char, String and Symbol.

Stable Types

A stable type is a singleton type, a literal type, or a type that is declared to be a subtype of trait scala.Singleton.

Type Projection

SimpleType  ::=  SimpleType ‘#’ id

A type projection $T$#$x$ references the type member named $x$ of type $T$.

Type Designators

SimpleType  ::=  StableId

A type designator refers to a named value type. It can be simple or qualified. All such type designators are shorthands for type projections.

Specifically, the unqualified type name $t$ where $t$ is bound in some class, object, or package $C$ is taken as a shorthand for $C.$this.type#$t$. If $t$ is not bound in a class, object, or package, then $t$ is taken as a shorthand for ε.type#$t$.

A qualified type designator has the form p.t where p is a path and t is a type name. Such a type designator is equivalent to the type projection p.type#t.

Some type designators and their expansions are listed below. We assume a local type parameter $t$, a value maintable with a type member Node and the standard class scala.Int,

Designator	Expansion
t	ε.type#t
Int	scala.type#Int
scala.Int	scala.type#Int
data.maintable.Node	data.maintable.type#Node

Parameterized Types

SimpleType      ::=  SimpleType TypeArgs
TypeArgs        ::=  ‘[’ Types ‘]’

A parameterized type $T[ T_1 , \ldots , T_n ]$ consists of a type designator $T$ and type parameters $T_1 , \ldots , T_n$ where $n \geq 1$.
$T$ must refer to a type constructor which takes $n$ type parameters $a_1 , \ldots , a_n$.

Say the type parameters have lower bounds $L_1 , \ldots , L_n$ and upper bounds $U_1, \ldots, U_n$. The parameterized type is well-formed if each actual type parameter conforms to its bounds, i.e. $\sigma L_i <: T_i <: \sigma U_i$ where $\sigma$ is the substitution $[ a_1 := T_1 , \ldots , a_n := T_n ]$.

Given the partial type definitions:

class TreeMap[A <: Comparable[A], B] { … }
class List[A] { … }
class I extends Comparable[I] { … }

class F[M[_], X] { … }
class S[K <: String] { … }
class G[M[ Z <: I ], I] { … }

Copy

the following parameterized types are well formed:

TreeMap[I, String]
List[I]
List[List[Boolean]]

F[List, Int]
G[S, String]

Copy

Given the above type definitions, the following types are ill-formed:

TreeMap[I]            // illegal: wrong number of parameters
TreeMap[List[I], Int] // illegal: type parameter not within bound

F[Int, Boolean]       // illegal: Int is not a type constructor
F[TreeMap, Int]       // illegal: TreeMap takes two parameters,
                      //   F expects a constructor taking one
G[S, Int]             // illegal: S constrains its parameter to
                      //   conform to String,
                      // G expects type constructor with a parameter
                      //   that conforms to Int

Copy

Tuple Types

SimpleType    ::=   ‘(’ Types ‘)’

A tuple type $(T_1 , \ldots , T_n)$ is an alias for the class scala.Tuple$_n$[$T_1$, … , $T_n$], where $n \geq 2$.

Tuple classes are case classes whose fields can be accessed using selectors _1 , … , _n. Their functionality is abstracted in a corresponding Product trait. The n-ary tuple class and product trait are defined at least as follows in the standard Scala library (they might also add other methods and implement other traits).

case class Tuple$_n$[+$T_1$, … , +$T_n$](_1: $T_1$, … , _n: $T_n$)
extends Product$_n$[$T_1$, … , $T_n$]

trait Product$_n$[+$T_1$, … , +$T_n$] {
  override def productArity = $n$
  def _1: $T_1$
  …
  def _n: $T_n$
}

Annotated Types

AnnotType  ::=  SimpleType {Annotation}

An annotated type $T$ $a_1, \ldots, a_n$ attaches annotations $a_1 , \ldots , a_n$ to the type $T$.

The following type adds the @suspendable annotation to the type String:

String @suspendable

Copy

Compound Types

CompoundType    ::=  AnnotType {‘with’ AnnotType} [Refinement]
                  |  Refinement
Refinement      ::=  [nl] ‘{’ RefineStat {semi RefineStat} ‘}’
RefineStat      ::=  Dcl
                  |  ‘type’ TypeDef
                  |

A compound type $T_1$ with … with $T_n \{ R \}$ represents objects with members as given in the component types $T_1 , \ldots , T_n$ and the refinement $\{ R \}$. A refinement $\{ R \}$ contains declarations and type definitions. If a declaration or definition overrides a declaration or definition in one of the component types $T_1 , \ldots , T_n$, the usual rules for overriding apply; otherwise the declaration or definition is said to be “structural” $^2$.

Within a method declaration in a structural refinement, the type of any value parameter may only refer to type parameters or abstract types that are contained inside the refinement. That is, it must refer either to a type parameter of the method itself, or to a type definition within the refinement. This restriction does not apply to the method's result type.

If no refinement is given, the empty refinement is implicitly added, i.e. $T_1$ with … with $T_n$ is a shorthand for $T_1$ with … with $T_n \{\}$.

A compound type may also consist of just a refinement $\{ R \}$ with no preceding component types. Such a type is equivalent to AnyRef $\{ R \}$.

The following example shows how to declare and use a method which has a parameter type that contains a refinement with structural declarations.

case class Bird (val name: String) extends Object {
  def fly(height: Int) = …
}
case class Plane (val callsign: String) extends Object {
  def fly(height: Int) = …
}
def takeoff(
  runway: Int,
  r: { val callsign: String; def fly(height: Int) }
) = {
  tower.print(r.callsign + " requests take-off on runway " + runway)
  tower.read(r.callsign + " is clear for take-off")
  r.fly(1000)
}
val bird = new Bird("Polly the parrot"){ val callsign = name }
val a380 = new Plane("TZ-987")
takeoff(42, bird)
takeoff(89, a380)

Copy

Although Bird and Plane do not share any parent class other than Object, the parameter r of method takeoff is defined using a refinement with structural declarations to accept any object that declares a value callsign and a fly method.

$^2$ A reference to a structurally defined member (method call or access to a value or variable) may generate binary code that is significantly slower than an equivalent code to a non-structural member.

Infix Types

InfixType     ::=  CompoundType {id [nl] CompoundType}

An infix type $T_1$ op $T_2$ consists of an infix operator op which gets applied to two type operands $T_1$ and $T_2$. The type is equivalent to the type application op$[T_1, T_2]$. The infix operator op may be an arbitrary identifier.

All type infix operators have the same precedence; parentheses have to be used for grouping. The associativity of a type operator is determined as for term operators: type operators ending in a colon ‘:’ are right-associative; all other operators are left-associative.

In a sequence of consecutive type infix operations $t_0 , \mathit{op} , t_1 , \mathit{op_2} , \ldots , \mathit{op_n} , t_n$, all operators $\mathit{op}_1 , \ldots , \mathit{op}_n$ must have the same associativity. If they are all left-associative, the sequence is interpreted as $(\ldots (t_0 \mathit{op_1} t_1) \mathit{op_2} \ldots) \mathit{op_n} t_n$, otherwise it is interpreted as $t_0 \mathit{op_1} (t_1 \mathit{op_2} ( \ldots \mathit{op_n} t_n) \ldots)$. )

Function Types

Type              ::=  FunctionArgs ‘=>’ Type
FunctionArgs      ::=  InfixType
                    |  ‘(’ [ ParamType {‘,’ ParamType } ] ‘)’

The type $(T_1 , \ldots , T_n) \Rightarrow U$ represents the set of function values that take arguments of types $T_1 , \ldots , Tn$ and yield results of type $U$. In the case of exactly one argument type $T \Rightarrow U$ is a shorthand for $(T) \Rightarrow U$. An argument type of the form $\Rightarrow T$ represents a call-by-name parameter of type $T$.

Function types associate to the right, e.g. $S \Rightarrow T \Rightarrow U$ is the same as $S \Rightarrow (T \Rightarrow U)$.

Function types are shorthands for class types that define apply functions. Specifically, the $n$-ary function type $(T_1 , \ldots , T_n) \Rightarrow U$ is a shorthand for the class type Function$_n$[$-T_1$ , ... , $T_n$, $U$]. Such class types are defined in the Scala library for $n$ between 0 and 22 as follows.

package scala
trait Function$_n$[$-T_1$-T_1 , ... , $-T_n$-T_n, $$+U+U] {
  def apply($x1$: $T_1$ , ... , $x_n$: $T_n$): $U$
  override def toString = "<function>"
}

Hence, function types are covariant in their result type and contravariant in their argument types.

Existential Types

Type               ::= InfixType ExistentialClauses
ExistentialClauses ::= ‘forSome’ ‘{’ ExistentialDcl
                      {semi ExistentialDcl} ‘}’
ExistentialDcl     ::= ‘type’ TypeDcl
                    |  ‘val’ ValDcl

An existential type has the form $T$ forSome { $Q$ } where $Q$ is a sequence of type declarations.

Let $t_1[\mathit{tps}_1] >: L_1 <: U_1 , \ldots , t_n[\mathit{tps}_n] >: L_n <: U_n$ be the types declared in $Q$ (any of the type parameter sections [ $\mathit{tps}_i$ ] might be missing). The scope of each type $t_i$ includes the type $T$ and the existential clause $Q$. The type variables $t_i$ are said to be bound in the type $T$ forSome { $Q$ }. Type variables which occur in a type $T$ but which are not bound in $T$ are said to be free in $T$.

A type instance of $T$ forSome { $Q$ } is a type $\sigma T$ where $\sigma$ is a substitution over $t_1 , \ldots , t_n$ such that, for each $i$, $\sigma L_i <: \sigma t_i <: \sigma U_i$. The set of values denoted by the existential type $T$ forSome {$\,Q\,$} is the union of the set of values of all its type instances.

A skolemization of $T$ forSome { $Q$ } is a type instance $\sigma T$, where $\sigma$ is the substitution $[t_1'/t_1 , \ldots , t_n'/t_n]$ and each $t_i'$ is a fresh abstract type with lower bound $\sigma L_i$ and upper bound $\sigma U_i$.

WildcardType   ::=  ‘_’ TypeBounds

$p$.c[targs,t,targs′]p.c[\mathit{targs},t,\mathit{targs}&#x27;] forSome { type $t$ >: $L$ <: $U$ }

Method Types

A method type is denoted internally as $(\mathit{Ps})U$, where $(\mathit{Ps})$ is a sequence of parameter names and types $(p_1:T_1 , \ldots , p_n:T_n)$ for some $n \geq 0$ and $U$ is a (value or method) type.
This type represents named methods that take arguments named $p_1 , \ldots , p_n$ of types $T_1 , \ldots , T_n$ and that return a result of type $U$.

Method types associate to the right: $(\mathit{Ps}_1)(\mathit{Ps}_2)U$ is treated as $(\mathit{Ps}_1)((\mathit{Ps}_2)U)$.

A special case are types of methods without any parameters. They are written here => T. Parameterless methods name expressions that are re-evaluated each time the parameterless method name is referenced.

Method types do not exist as types of values. If a method name is used as a value, its type is implicitly converted to a corresponding function type.

The declarations

def a: Int
def b (x: Int): Boolean
def c (x: Int) (y: String, z: String): String

Copy

produce the typings

a: => Int
b: (Int) Boolean
c: (Int) (String, String) String

Copy

Polymorphic Method Types

A polymorphic method type is denoted internally as [$\mathit{tps}\,$]$T$ where [$\mathit{tps}\,$] is a type parameter section [$a_1$ >: $L_1$ <: $U_1 , \ldots , a_n$ >: $L_n$ <: $U_n$] for some $n \geq 0$ and $T$ is a (value or method) type. This type represents named methods that take type arguments $S_1 , \ldots , S_n$ which conform to the lower bounds $L_1 , \ldots , L_n$ and the upper bounds $U_1 , \ldots , U_n$ and that yield results of type $T$.

The declarations

def empty[A]: List[A]
def union[A <: Comparable[A]] (x: Set[A], xs: Set[A]): Set[A]

Copy

produce the typings

empty : [A >: Nothing <: Any] List[A]
union : [A >: Nothing <: Comparable[A]] (x: Set[A], xs: Set[A]) Set[A]

Copy

Type Constructors

A type constructor is represented internally much like a polymorphic method type. [$\pm$ $a_1$ >: $L_1$ <: $U_1 , \ldots , \pm a_n$ >: $L_n$ <: $U_n$] $T$ represents a type that is expected by a type constructor parameter or an abstract type constructor binding with the corresponding type parameter clause.

Consider this fragment of the Iterable[+X] class:

trait Iterable[+X] {
  def flatMap[newType[+X] <: Iterable[X], S](f: X => newType[S]): newType[S]
}

Copy

Conceptually, the type constructor Iterable is a name for the anonymous type [+X] Iterable[X], which may be passed to the newType type constructor parameter in flatMap.

Equivalence

Equivalence $(\equiv)$ between types is the smallest congruence $^3$ such that the following holds:

• If $t$ is defined by a type alias type $t$ = $T$, then $t$ is equivalent to $T$.
• If a path $p$ has a singleton type $q$.type, then $p$.type $\equiv q$.type.
• If $O$ is defined by an object definition, and $p$ is a path consisting only of package or object selectors and ending in $O$, then $O$.this.type $\equiv p$.type.
• Two compound types are equivalent if the sequences of their component are pairwise equivalent, and occur in the same order, and their refinements are equivalent. Two refinements are equivalent if they bind the same names and the modifiers, types and bounds of every declared entity are equivalent in both refinements.
• Two method types are equivalent if:
  • neither are implicit, or they both are $^4$;
  • they have equivalent result types;
  • they have the same number of parameters; and
  • corresponding parameters have equivalent types. Note that the names of parameters do not matter for method type equivalence.
• Two polymorphic method types are equivalent if they have the same number of type parameters, and, after renaming one set of type parameters by another, the result types as well as lower and upper bounds of corresponding type parameters are equivalent.
• Two existential types are equivalent if they have the same number of quantifiers, and, after renaming one list of type quantifiers by another, the quantified types as well as lower and upper bounds of corresponding quantifiers are equivalent.
• Two type constructors are equivalent if they have the same number of type parameters, and, after renaming one list of type parameters by another, the result types as well as variances, lower and upper bounds of corresponding type parameters are equivalent.

$^3$ A congruence is an equivalence relation which is closed under formation of contexts.
$^4$ A method type is implicit if the parameter section that defines it starts with the implicit keyword.

Conformance

The conformance relation $(<:)$ is the smallest transitive relation that satisfies the following conditions.

• Conformance includes equivalence. If $T \equiv U$ then $T <: U$.
• For every value type $T$, scala.Nothing <: $T$ <: scala.Any.
• For every type constructor $T$ (with any number of type parameters), scala.Nothing <: $T$ <: scala.Any.
• For every class type $T$ such that $T$ <: scala.AnyRef one has scala.Null <: $T$.
• A type variable or abstract type $t$ conforms to its upper bound and its lower bound conforms to $t$.
• A class type or parameterized type conforms to any of its base-types.
• A singleton type $p$.type conforms to the type of the path $p$.
• A singleton type $p$.type conforms to the type scala.Singleton.
• A type projection $T$#$t$ conforms to $U$#$t$ if $T$ conforms to $U$.
• A parameterized type $T$[$T_1$ , … , $T_n$] conforms to $T$[$U_1$ , … , $U_n$] if the following three conditions hold for $i \in { 1 , \ldots , n }$:
  1. If the $i$'th type parameter of $T$ is declared covariant, then $T_i <: U_i$.
  2. If the $i$'th type parameter of $T$ is declared contravariant, then $U_i <: T_i$.
  3. If the $i$'th type parameter of $T$ is declared neither covariant nor contravariant, then $U_i \equiv T_i$.
• A compound type $T_1$ with $\ldots$ with $T_n$ {$R\,$} conforms to each of its component types $T_i$.
• If $T <: U_i$ for $i \in { 1 , \ldots , n }$ and for every binding $d$ of a type or value $x$ in $R$ there exists a member binding of $x$ in $T$ which subsumes $d$, then $T$ conforms to the compound type $U_1$ with $\ldots$ with $U_n$ {$R\,$}.
• The existential type $T$ forSome {$\,Q\,$} conforms to $U$ if its skolemization conforms to $U$.
• The type $T$ conforms to the existential type $U$ forSome {$\,Q\,$} if $T$ conforms to one of the type instances of $U$ forSome {$\,Q\,$}.
• If $T_i \equiv T_i'$ for $i \in { 1 , \ldots , n}$ and $U$ conforms to $U'$ then the method type $(p_1:T_1 , \ldots , p_n:T_n) U$ conforms to $(p_1':T_1' , \ldots , p_n':T_n') U'$.
• The polymorphic type $[a_1 >: L_1 <: U_1 , \ldots , a_n >: L_n <: U_n] T$ conforms to the polymorphic type $[a_1 >: L_1' <: U_1' , \ldots , a_n >: L_n' <: U_n'] T'$ if, assuming $L_1' <: a_1 <: U_1' , \ldots , L_n' <: a_n <: U_n'$ one has $T <: T'$ and $L_i <: L_i'$ and $U_i' <: U_i$ for $i \in { 1 , \ldots , n }$.
• Type constructors $T$ and $T'$ follow a similar discipline. We characterize $T$ and $T'$ by their type parameter clauses $[a_1 , \ldots , a_n]$ and $[a_1' , \ldots , a_n']$, where an $a_i$ or $a_i'$ may include a variance annotation, a higher-order type parameter clause, and bounds. Then, $T$ conforms to $T'$ if any list $[t_1 , \ldots , t_n]$ -- with declared variances, bounds and higher-order type parameter clauses -- of valid type arguments for $T'$ is also a valid list of type arguments for $T$ and $T[t_1 , \ldots , t_n] <: T'[t_1 , \ldots , t_n]$. Note that this entails that:
  • The bounds on $a_i$ must be weaker than the corresponding bounds declared for $a'_i$.
  • The variance of $a_i$ must match the variance of $a'_i$, where covariance matches covariance, contravariance matches contravariance and any variance matches invariance.
  • Recursively, these restrictions apply to the corresponding higher-order type parameter clauses of $a_i$ and $a'_i$.

A declaration or definition in some compound type of class type $C$ subsumes another declaration of the same name in some compound type or class type $C'$, if one of the following holds.

• A value declaration or definition that defines a name $x$ with type $T$ subsumes a value or method declaration that defines $x$ with type $T'$, provided $T <: T'$.
• A method declaration or definition that defines a name $x$ with type $T$ subsumes a method declaration that defines $x$ with type $T'$, provided $T <: T'$.
• A type alias type $t$[$T_1$ , … , $T_n$] = $T$ subsumes a type alias type $t$[$T_1$ , … , $T_n$] = $T'$ if $T \equiv T'$.
• A type declaration type $t$[$T_1$ , … , $T_n$] >: $L$ <: $U$ subsumes a type declaration type $t$[$T_1$ , … , $T_n$] >: $L&#x27;$ <: $U&#x27;$ if $L' <: L$ and $U <: U'$.
• A type or class definition that binds a type name $t$ subsumes an abstract type declaration type t[$T_1$ , … , $T_n$] >: L <: U if $L <: t <: U$.

class A[+T] {}
class B extends A[B]
class C extends A[C]

Weak Conformance

In some situations Scala uses a more general conformance relation. A type $S$ weakly conforms to a type $T$, written $S <:_w T$, if $S <: T$ or both $S$ and $T$ are primitive number types and $S$ precedes $T$ in the following ordering.

Byte  $$<:w<:_w Short
Short $$<:w<:_w Int
Char  $$<:w<:_w Int
Int   $$<:w<:_w Long
Long  $$<:w<:_w Float
Float $$<:w<:_w Double

A weak least upper bound is a least upper bound with respect to weak conformance.

Compatibility

A type $T$ is compatible to a type $U$ if $T$ (or its corresponding function type) weakly conforms to $U$ after applying eta-expansion. If $T$ is a method type, it's converted to the corresponding function type. If the types do not weakly conform, the following alternatives are checked in order:

• view application: there's an implicit view from $T$ to $U$
• dropping by-name modifiers: if $U$ is of the shape $=> U'$ (and $T$ is not), $T <:_w U'$
• SAM conversion: if $T$ corresponds to a function type, and $U$ declares a single abstract method whose type corresponds to the function type $U'$, $T <:_w U'$

Function compatibility via SAM conversion

Given the definitions

def foo(x: Int => String): Unit
def foo(x: ToString): Unit

trait ToString { def convert(x: Int): String }

Copy

The application foo((x: Int) => x.toString) resolves to the first overload, as it's more specific:

• Int => String is compatible to ToString -- when expecting a value of type ToString, you may pass a function literal from Int to String, as it will be SAM-converted to said function;
• ToString is not compatible to Int => String -- when expecting a function from Int to String, you may not pass a ToString.