1. Introduction
An enumeration is a finite set of ordered values representing a domain or a collection. Enumerations, or Enums, are very widely used in many programming languages to model the domain. Scala also supports enumerations. However, there are some practical problems with Scala’s in-built enum type. In this tutorial, we’ll take a look at Enumeratum, an improved enumeration library for Scala.
2. Existing Ways to Create Enums
Let’s take a look at how enumerations are currently created in Scala.
2.1. Using Enumeration Keyword
The in-built method to create enumerations in Scala is done by extending with the abstract class Enumeration. However, there are some major issues with this approach, such as:
- The JVM erases Enumerations at run-time
- No exhaustive check for pattern matching at compile time
2.2. Using Algebraic Data Type (ADT)
Due to the issues with Scala’s Enumeration, enums are often created as ADTs using sealed traits and case objects. This solves some of the issues, but there are still some drawbacks to this approach. Some drawbacks include:
- No out-of-the-box solution to build and list enumerations
- No automatic ordering for the items
- Need to write custom logic for serialization and deserialization
3. Enumeratum
The Enumeratum library tries to solve all the previously mentioned issues. Some of the advantages of using Enumeratum are:
- Exhaustive pattern-matching warning
- Very fast and easy to use
- Many in-built utility methods to customize enumerations
- Very good integration with popular JSON and database libraries
3.1. Setup
To use Enumeratum, we first need to add the library dependency:
libraryDependencies ++= Seq(
"com.beachape" %% "enumeratum" % "1.7.0"
)
Then, we can import enumeratum._ in our code and the required classes will be available in scope.
3.2. Defining a Simple Enum
Let’s look at how we can define a simple enum. We’ll be using the types EnumEntry and Enum to define our enumerations. First, we’ll create a sealed trait, or abstract class, to define our enum type. For this, we’ll extend the trait EnumEntry:
sealed trait Country extends EnumEntry
Now, let’s define a list of countries:
object Country extends Enum[Country] {
case object Germany extends Country
case object India extends Country
override val values: IndexedSeq[Country] = findValues
}
Notice that we’re implementing the values field, with the list of possible values. Enumeratum provides a method findValues that returns all the defined enum elements in the same order in which they’re defined. Let’s verify the above implementation:
val countries = Country.values
assert(countries.size == 2)
assert(countries.equals(Seq(Country.Germany, Country.India)))
3.3. Utility Methods
Enumeratum provides many utility methods on enum values. Let’s look at some popular and useful ones. We can convert a String value to enum using the withName() method:
Country.withName("India")
If the value is not a valid enum name, it will throw a NoSuchElementException at runtime. To handle such cases, we can use the withNameOption method:
val usa: Option[Country] = Country.withNameOption("USA")
This will return None if the value passed is an invalid enum name. Otherwise, it will be wrapped in Some. Additionally, there are methods to handle case sensitivity:
val germanyCaps = Country.withNameInsensitive("GERMANY")
assert(germanyCaps == Country.Germany)
val indiaMixed = Country.withNameInsensitive("iNDia")
assert(indiaMixed == Country.India)
val usaInsensitive = Country.withNameInsensitiveOption("uSA")
assert(usaInsensitive.isEmpty)
3.4. Customizing Enum Values Using override
By default, the enum value will be the same as the case object name. However, we can customize this name by overriding the entryName parameter:
sealed abstract class Gender(override val entryName: String) extends EnumEntry
object Gender extends Enum[Gender]{
override def values: IndexedSeq[Gender] = findValues
case object Male extends Gender("M")
case object Female extends Gender("F")
case object Other extends Gender("O")
}
Now, the enum values will be overridden to M, F, and O instead of Male, Female, and Other:
val male = Gender.withName("M")
assert(male == Gender.Male)
3.5. Customizing Enum Values Using Utility Traits
Instead of overriding the enum values explicitly, Enumeratum provides a set of utility traits for common scenarios. We can use these traits to extend our enum entries. These traits will internally override the entryName parameter with some of the common String conversions. Let’s look at an example:
sealed trait NamingConvention extends EnumEntry with EnumEntry.LowerCamelcase
object NamingConvention extends Enum[NamingConvention] {
override val values: IndexedSeq[NamingConvention] = findValues
case object JavaStyle extends NamingConvention
case object ScalaStyle extends NamingConvention
case object PythonStyle extends NamingConvention with EnumEntry.Snakecase
}
The trait NamingConvention is extending a trait EnumEntry.LowerCamelcase, which will modify the entryName parameter. This is equivalent to explicitly defining a JavaStyle enum as:
sealed abstract class NamingConvention(override val entryName: String) extends EnumEntry
object NamingConvention extends Enum[NamingConvention] {
override val values: IndexedSeq[NamingConvention] = findValues
case object JavaStyle extends NamingConvention("javaStyle")
case object ScalaStyle extends NamingConvention("scalaStyle")
case object PythonStyle extends NamingConvention("python_style")
}
3.6. Defining Value Enums
Apart from the regular String-based enums, Enumeratum* also supports Int, Long, *Char, and so on. Instead of extending with EnumEntry, we need to use the more specific type like IntEnumEntry, LongEnumEntry, and so on:
import enumeratum.values._
sealed abstract class HttpCode(val value:Int, val name:String) extends IntEnumEntry
object HttpCode extends IntEnum[HttpCode] {
override val values: IndexedSeq[HttpCode] = findValues
case object OK extends HttpCode(200, "Ok")
case object BadRequest extends HttpCode(400, "Bad Request")
}
Now, we can create the enum using the integer value:
val bad = HttpCode.withValue(400)
assert(bad == HttpCode.BadRequest)
assert(bad.name == "Bad Request")
4. Integration with Other Libraries
Enumeratum has very good integration with other libraries such as JSON libraries and database libraries. Some of the supported libraries are Json4s, Play, Slick, ReactiveMongo, and Circe.
5. Conclusion
In this article, we looked at the drawbacks of enumerations in Scala and how we can use Enumeratum to handle enums in a better way. As always, the sample code used in this tutorial is available over on GitHub.