Stay on Target

Pimp My Library: 5.minutes with the Time And Money Library

When I was learning to use Ruby on Rails, I was impressed by how the framework made expressing units of time so readble: "5.minutes" or "2.weeks". This was achieved by adding methods to the Numeric class, using Ruby's Open Classes.

As a developer new to Scala, I thought it would be an interesting exercise to implement this feature using The Scala Way: implicit conversions. I'm using the Java Time and Money Library which demonstrates the principles from the Domain-Driven Design book. I wrote the library test-first using the expressive ScalaCheck testing framework, but have yet to use the library in a real application.

I'm posting my work so far in case:

• anyone has feedback or suggestions to improve the code
• anyone can actually use it (and make it better)

I've found the Scala community to be a very helpful and smart bunch of folks - thank you for your advice!

The Code

package com.danielwellman.timeandmoneysugar

import com.domainlanguage.time.Duration


object RichDurationUnits {
  implicit def intToRichDurationUnits(value: Int) = new RichDurationUnits(value)
}

class RichDurationUnits(value: Int) {
  def milliseconds = Duration.milliseconds(value)
  def seconds = Duration.seconds(value)
  def minutes = Duration.minutes(value)
  def hours = Duration.hours(value)
  def days = Duration.days(value)
  def weeks = Duration.weeks(value)
  def months = Duration.months(value)
  def quarters = Duration.quarters(value)
  def years = Duration.years(value)
}

object RichDuration {
  implicit def intToRichDuration(value: Duration) = new RichDuration(value)
}

class RichDuration(value: Duration) {
  /**
   * Add two RichDurations using Duration's plus method.
   *
   * Note that it is a runtime error to add two Durations of unequal base units,
   * such as seconds and months.  Since Duration itself does not use types to
   * guard against this problem, this library doesn't either.
   */
  def +(other: Duration) = value.plus(other)
}

Usage Examples

Here's an example of using the enhancements to Integers:

scala> import com.danielwellman.timeandmoneysugar._
import com.danielwellman.timeandmoneysugar._

scala> import RichDurationUnits._
import RichDurationUnits._

scala> 5.minutes
res0: com.domainlanguage.time.Duration = 5 minutes

scala> 2 weeks
res1: com.domainlanguage.time.Duration = 14 days

Note also the example of "2 weeks" doesn't use a period at all, since the Scala compiler will try to insert a period for you.

Here's an example of using the + operator with Durations as well as the sugar for Integers:

scala> import RichDuration._
import RichDuration._

scala> 2.days + 5.days
res2: com.domainlanguage.time.Duration = 7 days

scala> 2.minutes + 2.weeks
res3: com.domainlanguage.time.Duration = 14 days, 2 minutes

scala> 2.minutes + 2.months
java.lang.IllegalArgumentException: 2 months is not convertible to: 2 minutes
	at com.domainlanguage.time.Duration.assertNotConvertible(Unknown Source)
	at com.domainlanguage.time.Duration.plus(Unknown Source)
	at com.danielwellman.timeandmoneysugar.RichDuration.$plus(RichDurationUnits.scala:37)
	at .(:11)
	at .()
	at RequestResult$.(:3)
...

The last addition exposes a feature of the Time And Money library; you can't sensibly add two minutes and two months. I think it should be possible to use the Scala type system to prevent addition of two unrelated units, but haven't tried to do that yet.

I have found that using spaces can lead to some confusion. For example:

scala> 5 minutes + 2 minutes
:11: error: timeandmoneysugar.this.RichDurationUnits.intToRichDurationUnits(5).minutes of 
  type com.domainlanguage.time.Duration does not take parameters
       5 minutes + 2 minutes
         ^

Here I believe the compiler is trying to parse the "+ 2 minutes" expression as an argument to the "minutes" method of RichDuration. In this case, you need to wrap some of the arguments to give the compiler a hint, like so:

scala> (5 minutes) + (2 minutes)
res8: com.domainlanguage.time.Duration = 7 minutes

References

Here are some articles I found useful while learning about implicit conversions:

• Pimp My Library at the Scala wiki
• Martin Odersky's article at Artima.com

Looking at Streams in Scala

Scala offers a a few powerful abstractions for working with sequences of values. Functional programming style encourages moving from mutable variables and state changes to declarative lists of all known states. Higher order functions like map, flatMap, and filter can very succinctly represent complex requirements.

For example, suppose you were writing a search engine and a user asked for the 10th document about Scala in a database of 10,0000 HTML documents. In a functional style, you might declare the list of all documents, compute the score for each one, and then pick the 10th item. This might look like something like this:

documents.filter(isAboutScala)(9)

The problem is that if you've got 10,000 big HTML documents, you'll need to first ask each one of 10,000 if they're about Scala to build the filtered list -- only to take the 10th document. Clearly this overhead won't scale well!

One solution is to use Scala's Stream construct; which is like a List which lazily evaluates the next item only when needed. Using a Stream would only evaluate enough documents to find the 10th match - instead of first evaluating the 10,000 documents.

For a full introduction to Streams, see the chapter "Computing with Streams" in "Scala By Example".

So how do Streams work? How is the lazy evaluation defined? Looking in to the implementation of Stream reveals many nice things about the Scala language and some of the philosophies adopted for building libraries.

The syntax for constructing a Stream requires using Stream.cons and Stream.empty:

Stream.cons(3, Stream.cons(4, Stream.empty))

Upon initial inspection, it looks like cons is a method call on the Stream object. It turns out cons is actually a nested object in the Stream object.

Stream.cons is an object, not a method on the Stream object

Looking at Stream.scala in the Scala libraries source shows this structure:

object Stream {
  object cons {
    // ... definition of Stream.cons object
  }
  // ... rest of Stream
}

This nesting of objects is also possible in Java. However, Scala's use of the apply() function (which we'll look at below) means that a method invocation on the nested cons object looks like a method call on the Stream object.

Syntactic sugar and the apply() method

Recall that a Scala object may define a method apply() like so:

object List {
  def apply[A](xs: A*): List[A] = xs.toList
  // ...
}

This means you can call the List object to create the list of items 1, 2, and 3 with this syntax:

val usingApply = List.apply(1, 2, 3)

or using Scala syntactic sugar:

val usingSugar = List(1, 2, 3)

For me, the combination of apply()'s syntactic sugar and nested singleton objects begin to describe the 'scalable language' idea that the Scala literature talks about so frequently. What looks like a method call is really a call to a nested object's apply method, but the syntax reads identically. The end user doesn't need to know if you're talking to a nested singleton object in a library class; it is no different than a standard function call.

But how does Stream's lazy evaluation work?

Call by name evaluation

Let's look again at Stream.cons' apply method signature:

def apply[A](head : A, tail : => Stream[A]) : Stream[A]

Note the => operator ; this indicates call-by-name evaluation. This is a form of lazy argument evaluation; the language will only evaluate tail if it needs to.

Thus, Scala allows you to construct an expensive list of items worry-free; the runtime will evaluate the Stream's items one-by-one until the specified conditions are met -- and will go no further.

To see more examples of Stream in action, check out this article about solving Project Euler problems in Scala.

Using Scala's Option class to help avoid NullPointerExceptions

Here's an intro to Scala's Option classes and why you'd want to use them. If you already know about Option classes, here is a useful blog entry about how to use Option classes with higher order functions instead of pattern matching:

http://blog.tmorris.net/scalaoption-cheat-sheet/

---

Scala's Option class provides a typesafe way to deal with cases where you have or don't have some result. A common example here is Java's HashMap class, which allows values to be null, e.g.

HashMap<String, String> map = new HashMap<String, String>();
map.put( "Hi", "Dan");
map.put( "Hello", null ");

We can get at our values:

map.get( "Hi" )  =>  returns "Dan", "Hi" is a key in the map
map.get( "Hello" )   =>  returns null, "Hello" is a key in the map

But what about when we ask for a key which doesn't exist?

map.get( "Gutentag" )  =>  also returns null, but "Gutentag" is not a key in the map

The problem is that using get doesn't tell you if the key existed or didn't exist. To do that, you need to first ask

map.containsKey( "Hello" )  => returns true
map.containsKey( "Gutentag" ) => returns false

This feels verbose; we'd need to check the key is contained first, then actually get it to avoid any problems.

Scala's Option type is designed to address this situation. Option has two subclasses: Some[T] and None -- note the parameterization with a type T. Some means that an object exists, but None means it doesn't.

Let's take a look at an example:

import scala.collection.mutable.HashMap
val map = new HashMap[String, String]
map.put( "Hi", "Dan" )
map.put( "Hello", null )

Here we've set up the same Map as we did in Java, but we imported Scala's mutable version of a HashMap. Now let's make the same queries into the map:

scala> map.get( "Hi" )
res1: Option[String] = Some(Dan)

Here the Map has the requested key, and returns a Some[String] which has contains the value of "Dan".

scala> map.get( "Hello" )
res2: Option[String] = Some(null)

In this case, the key does exist, so it returns a Some class containing the value null.

scala> map.get( "Gutentag" )
res3: Option[String] = None

But in this case, we call get back a None type, meaning that the key "Gutentag" doesn't exist at all.

So how do you deal with these Options, where you could get one of two different types in response to a method call? You can use pattern matching, or use higher-order functions.

Pattern matching allows you to explicitly specify the operations for the None and Some cases. For example, here's an example using pattern matching with our Map:

val result = map.get( "Hello" )

result match {
  case None => print "No key with that name!"
  case Some(x) => print "Found value" + x
}

Higher-order functions allow you to more succinctly declare your intended operation. This is possible because it turns out that the Some and None classes have sensible implementations of map, flatMap, foreach, etc. Here is a good blog entry which talks about ways of dealing with the Scala Option class using higher-order functions instead of pattern matching.

http://blog.tmorris.net/scalaoption-cheat-sheet/

Ultimately Scala's Option class requires that the programmer more explicitly handle conditions where data might be missing. In fact, the problem now gets handled by the compile-time type system -- if the user forgets to handle the case, Scala will generate a compile error.