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?

Obedient

Here is a related question which may answer your question at least partially: https://mcmap.net/q/128639/-lt-lt-operator-in-scala – Catenary

symbolhound.com is your code search friend :) – Incident

Do Haskell's typeclasses perform the job of these operators? Example: compare :: Ord a => a -> a -> Ordering? I'm trying to understand this Scala concept with respect to its Haskell counter-part. – Grigri

This might be useful to understnad operator =:=, #67774438 – Horwitz

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.

Gish

Well, ok, but there's also methods by the same names on Manifest, which you didn't mention. – Institutive

The methods on Manifest are <:< and >:> only... since OP mentioned exactly the 3 varieties of generalized type constraints, I'm assuming that's what he was interested in. – Gish

The error message the user will get when using the getStringLength function will not be very descriptive though... It reminds me C++'s errors. – Southport

How does the existence of the evidence makes the compiler think a.length is a valid call? – Mandorla

@IttayD: it's pretty clever... class =:=[From, To] extends From => To, which means that an implicit value of type From =:= To is actually an implicit conversion from From to To. So by accepting an implicit parameter of type A =:= String you're saying that A can be implicitly converted to String. If you changed the order and made the implicit argument be of type String =:= A, it wouldn't work, because this would be an implicit conversion from String to A. – Gish

Do those three-character symbols have names? My problem with Scala's symbol soup is that they're hard to talk about verbally, and it's practically impossible to use Google or any other search engine to find discussions and examples of their usage. – Teamster

I suggest A type-equal String: A =:= String, A subtype B: A <:< and A viewable B: A <%< B. – Barony

@Elazar: Scala 2.9.1 shows <console>:9: error: Cannot prove that Int =:= String. and points on the 'g' of new Foo(123).getStringLength. – Microcurie

@Lultz, I cannot prove that Int =:= String, because I have no idea what =:= means, and I've never requested to apply the mysteriously ungooglable =:= relation to an Int. – Southport

@pelotom If I understand correctly the implementation, then A =:= B will work not only if A is B, but also if there is an implicit conversion in scope, which maybe is not what you want. Is this right? – Zip

@Zip Nope, this will only work if the types are exactly equal. Note that I said that an having implicit value of type From =:= To in scope implies that you have an implicit conversion From => To, but the implication doesn't run backwards; having an implicit conversion A => B does not imply you have an instance of A =:= B. =:= is a sealed abstract class defined in scala.Predef, and has only one publicly exposed instance, which is implicit, and is of type A =:= A. So you're guaranteed that an implicit value of type A =:= B witnesses the fact that A and B are equal. – Gish

This did not answer "where are they documented"...unless that answer is "here". – Electrocorticogram

@PaulDraper The "official" documentation is here, but you'll probably find that less informative than explanations (such as this) that can be found by googling "scala generalized type constraints" – Gish

There is no A <%< B in Predef anymore - T <% Int generates (implicit evidence$1: T => Int) now, so no need for special symbol – Cynosure

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.

Playlet

needs upvote because makes use of Scala's alternative infix syntax for type operators. totally missing this explanation without which the whole thing doesn't make sense – Saturable

This makes a lot of sense. It's similar to pattern matching on List: case x :: xs => is actually a syntactic sugar for case ::(x, xs) => because :: is actually a final case class defined in the library. I had no idea you could use infix syntax in type namespace as well. Thank you! – Coverture

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

Aspen

I realize that this is years after this answer, but I am looking for use cases for <:<, and I think that the Ordered example is not so compelling anymore since now you would rather use the Ordering typeclass rather than the Ordered trait. Something like: def smaller(implicit ord: Ordering[T]) = if (ord.lt(first, second)) first else second. – Parish

@ebruchez: a use case is for encoding union types in unmodified scala, see milessabin.com/blog/2011/06/09/scala-union-types-curry-howard – Laurenelaurens

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.

Institutive

Is :-) another one of these? And I would agree that your answer to "When should I use them?" applies to a great many things. – Tuba

"They are meant to provide a way to test the relationship between the classes" <-- too general to be helpful – Obedient

"As for the question "when should I use them?", the answer is you shouldn't, unless you know you should." <-- That's why I'm asking. I'd like to be able to make that determination for myself. – Obedient