convert

A Scala library for handling conversions between types by throwing exceptions or returning Options containing the results

Add as a Dependency

SBT (Scala 2.11 and 2.12)

"com.nthportal" %% "convert" % "0.5.0"

Maven

Scala 2.12

<dependency>
  <groupId>com.nthportal</groupId>
  <artifactId>convert_2.12</artifactId>
  <version>0.5.0</version>
</dependency>

Scala 2.11

<dependency>
  <groupId>com.nthportal</groupId>
  <artifactId>convert_2.11</artifactId>
  <version>0.5.0</version>
</dependency>

Usage: As a Client

Suppose you wish to convert the a String to a BigDecimal using the following method:

import com.nthportal.convert.Convert

def parseBigDecimal(s: String)(implicit c: Convert): c.Result[BigDecimal] = ???

If you would like the method to throw an exception if the string does not represent a valid BigDecimal, invoke the method as follows (using "2.718281828" as an example string):

val e: BigDecimal = parseBigDecimal("2.718281828")(Convert.Throwing)

When using Convert.Throwing, the return type c.Result[BigDecimal] in the above method is just BigDecimal.

If you would like the method to return an Option containing the result if the string represents a valid BigDecimal, and None otherwise, invoke the method as follows (again, using "2.718281828" as an example string):

val e: Option[BigDecimal] = parseBigDecimal("2.718281828")(Convert.AsOption)

When using Convert.AsOption, the return type c.Result[BigDecimal] in the above method is Option[BigDecimal].

Alternatively, the Convert with the desired behaviour can be imported as an implicit, as in the following two examples:

import com.nthportal.convert.Convert.Throwing.Implicit.ref

val e: BigDecimal = parseBigDecimal("2.718281828")

import com.nthportal.convert.Convert.AsOption.Implicit.ref

val e: Option[BigDecimal] = parseBigDecimal("2.718281828")

Usage: In a Library

Basics

The core methods of Convert are conversion and fail. Additionally, unwrap is essential when chaining multiple conversions together.

To demonstrate how to use the first two of these methods, let's write a simple method to parse Booleans from Strings

import com.nthportal.convert.Convert

def parseBoolean(s: String)(implicit c: Convert): c.Result[Boolean] = {
  ??? // do parsing here
}

When using Convert, it is imperative that all parsing or conversion operations take place inside a conversion block

import com.nthportal.convert.Convert

def parseBoolean(s: String)(implicit c: Convert): c.Result[Boolean] = {
  c.conversion {
    ??? // do parsing here
  }
}

Now, let us implement the conversion by just checking if the (lowercase) string is equal to "true" or "false"

import com.nthportal.convert.Convert

def parseBoolean(s: String)(implicit c: Convert): c.Result[Boolean] = {
  c.conversion {
    s.toLowerCase match {
      case "true" => true
      case "false" => false
      case _ => ??? // it's not a valid boolean - now what? 
    }
  }
}

The final thing to do for this parsing method is to handle invalid inputs; to 'fail' the conversion. In Java, one would usually throw an exception. With Convert, instead of throwing the exception, you call the method fail with the exception you would have thrown

import com.nthportal.convert.Convert

def parseBoolean(s: String)(implicit c: Convert): c.Result[Boolean] = {
  c.conversion {
    s.toLowerCase match {
      case "true" => true
      case "false" => false
      case _ => c.fail(new IllegalArgumentException(s"$s wasn't 'true' or 'false'"))
    }
  }
}

What if you need to use the result of another conversion inside of yours? Suppose you want to be able to parse a comma-separated pair of Booleans. Let us write a simple method to do so which uses unwrap (note: unwrap MUST be called inside of the conversion block)

import com.nthportal.convert.Convert

def parseBoolean(s: String)(implicit c: Convert): c.Result[Boolean] = ??? // The same as defined above

def parseBooleanPair(s: String)(implicit c: Convert): c.Result[(Boolean, Boolean)] = {
  c.conversion {
    s split ',' match {
      case Array(a, b) => (c.unwrap(parseBoolean(a)), c.unwrap(parseBoolean(b)))
      case _ => c.fail(new IllegalArgumentException("Not a pair"))
    }
  }
}

Now you know how to write a conversion, and how to chain multiple conversions together!

Utility Methods

`require`

A common method used when parsing is require (defined in Predef). Unfortunately, Predef.require always throws an exception when it fails, which is not desirable if a caller wants an Option back. To solve this, Convert defines two require methods with signatures identical to the signatures of those in Predef. They can be used as drop-in replacements for latter (but MUST be called inside of a conversion block).

For example, let us write a simple method to convert a List of two elements to a Tuple2

import com.nthportal.convert.Convert

def list2Tuple[A](list: List[A])(implicit c: Convert): c.Result[(A, A)] = {
  c.conversion {
    c.require(list.size == 2, "List did not have exactly two elements")
    (list.head, list.tail.head)
  }
}

`wrapException`

Sometimes you may wish to use a conversion function which always throws exceptions, because you either cannot or do not want to re-implement it. For example, you may not wish to implement integer parsing, but instead use Java's Integer.parseInt. This can be accomplished easily using wrapException (which MUST be called inside of a conversion block) in either of the following ways:

import com.nthportal.convert.Convert

def parseInt1(s: String)(implicit c: Convert): c.Result[Int] = {
  c.conversion {
    c.wrapException[NumberFormatException, Int](Integer.parseInt(s))
  }
}

def parseInt2(s: String)(implicit c: Convert): c.Result[Int] = {
  c.conversion {
    c.wrapException(_.isInstanceOf[NumberFormatException])(Integer.parseInt(s))
  }
}

Synthesizing Conversions

Two functions, one of which throws exceptions, and one of which returns Options, can be synthesized into a single conversion function using Convert.synthesize. For example, suppose the following two methods to parse Booleans from Strings are defined:

def parseBooleanThrowing(s: String): Boolean = ???
def parseBooleanAsOption(s: String): Option[Boolean] = ???

They can be combined into a conversion function with Convert.synthesize

import com.nthportal.convert.Convert

val booleanParser: Convert.Conversion[String, Boolean] =
  Convert.synthesize(parseBooleanThrowing, parseBooleanAsOption)

Automatic Unwrapping (USE WITH CARE)

Sometimes, an excess of calls to Convert.unwrap can reduce code readability. Readability can be improved by importing Convert.AutoUnwrap.autoUnwrap - an implicit conversion from Convert#Result[T] to T. However, use of this implicit conversion is not without risks.

USE THIS IMPLICIT CONVERSION AT YOUR OWN RISK

This implicit conversion can improve code readability; however, it should be used with care. As with all implicit conversions, it may be difficult to tell when it is applied by the compiler, leading to unexpected behavior which is difficult to debug.

Additionally, because unwrap MUST be called within a conversion block, this implicit conversion MUST be called within a conversion block as well. However, if imported in the wrong scope, the compiler may insert a call to this implicit conversion outside of any conversion block.

Use this implicit conversion with care.

If you have decided to use automatic unwrapping, its benefits can be seen by revisiting the parseBooleanPair method from earlier. We originally defined the method as

import com.nthportal.convert.Convert

def parseBoolean(s: String)(implicit c: Convert): c.Result[Boolean] = ??? // The same as defined above

def parseBooleanPair(s: String)(implicit c: Convert): c.Result[(Boolean, Boolean)] = {
  c.conversion {
    s split ',' match {
      case Array(a, b) => (c.unwrap(parseBoolean(a)), c.unwrap(parseBoolean(b)))
      case _ => c.fail(new IllegalArgumentException("Not a pair"))
    }
  }
}

Using AutoUnwrap allows us to tidy it up a little bit

def parseBooleanPair(s: String)(implicit c: Convert): c.Result[(Boolean, Boolean)] = {
  c.conversion {
    import c.AutoUnwrap.autoUnwrap
    s split ',' match {
      case Array(a, b) => (parseBoolean(a), parseBoolean(b))
      case _ => c.fail(new IllegalArgumentException("Not a pair"))
    }
  }
}

AutoUnwrap makes it more clear that we are just returning a tuple from the results of calling parseBoolean on the two elements.

nthportal / convert 0.5.0