What do <:<, <%<, and =:= mean in Scala 2.8, and where are they documented?

Question

I can see in the API docs for Predef that they're subclasses of a generic function type (From) => To, but that's all it says. Um, what? Maybe there's documentation somewhere, but search engines don't handle "names" like "<:<" very well, so I haven't been able to find it.

Follow-up question: when should I use these funky symbols/classes, and why?

Answer 1

These are called generalized type constraints. They allow you, from within a type-parameterized class or trait, to further constrain one of its type parameters. Here's an example:

case class Foo[A](a:A) { // 'A' can be substituted with any type
    // getStringLength can only be used if this is a Foo[String]
    def getStringLength(implicit evidence: A =:= String) = a.length
}

The implicit argument evidence is supplied by the compiler, iff A is String. You can think of it as a proof that A is String--the argument itself isn't important, only knowing that it exists. [edit: well, technically it actually is important because it represents an implicit conversion from A to String, which is what allows you to call a.length and not have the compiler yell at you]

Now I can use it like so:

scala> Foo("blah").getStringLength
res6: Int = 4

But if I tried use it with a Foo containing something other than a String:

scala> Foo(123).getStringLength
<console>:9: error: could not find implicit value for parameter evidence: =:=[Int,String]

You can read that error as "could not find evidence that Int == String"... that's as it should be! getStringLength is imposing further restrictions on the type of A than what Foo in general requires; namely, you can only invoke getStringLength on a Foo[String]. This constraint is enforced at compile-time, which is cool!

<:< and <%< work similarly, but with slight variations:

• A =:= B means A must be exactly B
• A <:< B means A must be a subtype of B (analogous to the simple type constraint <:)
• A <%< B means A must be viewable as B, possibly via implicit conversion (analogous to the simple type constraint <%)

This snippet by @retronym is a good explanation of how this sort of thing used to be accomplished and how generalized type constraints make it easier now.

ADDENDUM

To answer your follow-up question, admittedly the example I gave is pretty contrived and not obviously useful. But imagine using it to define something like a List.sumInts method, which adds up a list of integers. You don't want to allow this method to be invoked on any old List, just a List[Int]. However the List type constructor can't be so constrainted; you still want to be able to have lists of strings, foos, bars, and whatnots. So by placing a generalized type constraint on sumInts, you can ensure that just that method has an additional constraint that it can only be used on a List[Int]. Essentially you're writing special-case code for certain kinds of lists.

Answer 2

Not a complete answer (others have already answered this), I just wanted to note the following, which maybe helps to understand the syntax better: The way you normally use these "operators", as for example in pelotom's example:

def getStringLength(implicit evidence: A =:= String)

makes use of Scala's alternative infix syntax for type operators.

So, A =:= String is the same as =:=[A, String] (and =:= is just a class or trait with a fancy-looking name). Note that this syntax also works with "regular" classes, for example you can write:

val a: Tuple2[Int, String] = (1, "one")

like this:

val a: Int Tuple2 String = (1, "one")

It's similar to the two syntaxes for method calls, the "normal" with . and () and the operator syntax.

Answer 3

Read the other answers to understand what these constructs are. Here is when you should use them. You use them when you need to constrain a method for specific types only.

Here is an example. Suppose you want to define a homogeneous Pair, like this:

class Pair[T](val first: T, val second: T)

Now you want to add a method smaller, like this:

def smaller = if (first < second) first else second

That only works if T is ordered. You could restrict the entire class:

class Pair[T <: Ordered[T]](val first: T, val second: T)

But that seems a shame--there could be uses for the class when T isn't ordered. With a type constraint, you can still define the smaller method:

def smaller(implicit ev: T <:< Ordered[T]) = if (first < second) first else second

It's ok to instantiate, say, a Pair[File], as long as you don't call smaller on it.

In the case of Option, the implementors wanted an orNull method, even though it doesn't make sense for Option[Int]. By using a type constraint, all is well. You can use orNull on an Option[String], and you can form an Option[Int] and use it, as long as you don't call orNull on it. If you try Some(42).orNull, you get the charming message

 error: Cannot prove that Null <:< Int

Answer 4

It depends on where they are being used. Most often, when used while declaring types of implicit parameters, they are classes. They can be objects too in rare instances. Finally, they can be operators on Manifest objects. They are defined inside scala.Predef in the first two cases, though not particularly well documented.

They are meant to provide a way to test the relationship between the classes, just like <: and <% do, in situations when the latter cannot be used.

As for the question "when should I use them?", the answer is you shouldn't, unless you know you should. :-) EDIT: Ok, ok, here are some examples from the library. On Either, you have:

/**
  * Joins an <code>Either</code> through <code>Right</code>.
  */
 def joinRight[A1 >: A, B1 >: B, C](implicit ev: B1 <:< Either[A1, C]): Either[A1, C] = this match {
   case Left(a)  => Left(a)
   case Right(b) => b
 }

 /**
  * Joins an <code>Either</code> through <code>Left</code>.
  */
 def joinLeft[A1 >: A, B1 >: B, C](implicit ev: A1 <:< Either[C, B1]): Either[C, B1] = this match {
   case Left(a)  => a
   case Right(b) => Right(b)
 }

On Option, you have:

def orNull[A1 >: A](implicit ev: Null <:< A1): A1 = this getOrElse null

You'll find some other examples on the collections.