How Does "20 Seconds" Work in Scala?

This short article will show you how apparently magical constructs like 20.seconds works in Scala, although the Int type doesn't have such methods natively.

This article will make more sense if you know the basics of implicits, but then again, if you do know how implicits work, there's only one step to understanding how these seemingly magical methods work, so I'll cover everything you need to know.

You can read this article over at Rock the JVM or watch it on YouTube or in the video below:

1. The "Problem"

The question we're addressing here is the following: the Int type has a very small set of methods and certainly the seconds method isn't one of them:

    Scala
   
xxxxxxxxxx

val womp = 20.seconds // compile error: symbol "seconds" not found

However, once we add a special import, it magically works:

    Scala
   
xxxxxxxxxx

import scala.concurrent.duration._
val aDuration = 20.seconds // works!

So how does the magical import work?

2. Enriching Types

The answer is not in the import itself, but in what's imported — the types and values that are imported might as well be in scope, and methods like .seconds would work just as fine. It's their structure that provides the magic. To understand how they work, we need to go back to implicits.

I'm not going to talk about all the functionality that the implicit keyword does in Scala — we'll probably do that in another article — but we are going to focus on one kind of implicits: implicit classes. Implicit classes are one-argument wrappers, i.e. a class with one constructor argument, with regular methods, fields, etc, except that they have the implicit keyword in their declaration:

    Scala
   
xxxxxxxxxx

implicit class MyRichString(string: String) {
  def fullStop: String = string + "."
}

If we removed the implicit keyword there, this would be a pretty uninteresting class. Adding implicit will add some special powers. We can either say

    Scala
   
xxxxxxxxxx

new MyRichString("This is a sentence").fullStop

or this:

    Scala
   
xxxxxxxxxx

"This is a sentence".fullStop

This works although the fullStop method doesn't exist for the String class. Normally, the code would not compile, but the compiler will add an extra step of searching for any implicit wrapping or conversion of a String value that might have the fullStop method, which in our case it does. So in reality, the compiler will rewrite our last call as

    Scala
   
xxxxxxxxxx

// "This is a sentence".fullStop beecomes:
new MyRichString("This is a sentence").fullStop

which is what we (explicitly) wrote earlier. This pattern provides what we call extension methods - libraries like Cats use this all the time.

3. Importing

If an implicit class like this is not written in the scope where we use the "magical" method, the code will not compile until we bring that implicit class into scope. This means an import. Usually, libraries (including the standard library) packs implicits into "Ops"-like objects:

    Scala
   
xxxxxxxxxx

package mylibrary
object MyStringOps {
    implicit class MyRichString(string: String) {
      def fullStop: String = string + "."
    }
}

and then later in our code, when we import it, we'll also have access to the extension method:

    Scala
   
xxxxxxxxxx

import mylibrary._
"Starting to get it".fullStop

The Scala duration package works in the same way: when you import scala.concurrent.duration._ you gain access to extension methods on the Int type that returns instances of Duration:

    Scala
   
xxxxxxxxxx

import scala.concurrent.duration._
20.seconds
500.millis