Idiomatic approach to Scala Value Classes

Question

Does anyone know if there is an idiomatic way to name the inner value of a Scala Value Class? Say I have a value class for a product id, is it better defined as:

case class ProductId(productId:String) extends AnyVal

case class ProductId(underlying:String) extends AnyVal

case class ProductId(value:String) extends AnyVal

?

Is it just a matter of preference or is there an idiomatic guideline?

I'm not aware of any standard. I tend to use `inner` as it's short and clear. — lmm, Dec 09 '14 at 14:21
I don't think that there is some idiomatic way to do this, cause value classes is just a nice trick for the compiler. But like @om-nom-nom told, `underlying` is quite common among different cases where you need to create some kind of a wrapper. — 4lex1v, Dec 09 '14 at 14:24
What is IIRC? SIP15 uses both underlying in the examples but does ``class C(val u: U) extends AnyVal`` in the definition, so I guess it could also be ``case class ProductId(string: String) extends AnyVal`` ? — Diego Martinoia, Dec 09 '14 at 16:15

pyrospade · Answer 1 · 2017-01-09T14:16:09.767

I generally like to use the following pattern -

final class ProductId(val underlying: String) extends AnyVal

This has the following benefits -

You can access the underlying value whenever you need
Prevent pattern matching on the constructor by not using a case class, which helps to avoid actually constructing the object so the runtime value stays as a String (or whatever your underlying value is)
You can create a smart constructor using a companion object to validate its input and provide a cleaner interface when constructing the value so the user doesn't have to use new.

Example of a smart constructor below -

final class ProductId(val underlying: String) extends AnyVal

object ProductId {
  def apply(s: String): Result = {
    if (s.isEmpty) {
      new Failure("ProductId cannot be empty!")
    } else {
      new Success(new ProductId(s))
    }
  }

  sealed trait Result
  final case class Success(productId: ProductId) extends Result
  final case class Failure(message: String) extends Result
}

If you want to ensure that users must use the smart constructor, mark your value class' constructor as private -

final class ProductId private (val underlying: String) extends AnyVal

If you want to ensure that you're not accidentally allocating an instance of ProductId, you can check the bytecode -

scala> :paste
class Test {
  def testProductId = new ProductId("foo")

  def testSmartCtor = ProductId("bar") match {
    case ProductId.Success(productId) => productId
    case ProductId.Failure(message) => throw new AssertionError(message)
  }
}

// Ctrl+D

:javap -c ProductId$

// Skipping to the apply() method

public ProductId$Result apply(java.lang.String);
  Code:
     0: aload_1
     1: invokevirtual #20                 // Method java/lang/String.isEmpty:()Z
     4: ifeq          19
     7: new           #22                 // class ProductId$Failure
    10: dup
    11: ldc           #24                 // String ProductId cannot be empty!
    13: invokespecial #27                 // Method ProductId$Failure."<init>":(Ljava/lang/String;)V
    16: goto          27
    19: new           #29                 // class ProductId$Success
    22: dup
    23: aload_1
    24: invokespecial #30                 // Method ProductId$Success."<init>":(Ljava/lang/String;)V
    27: areturn

There are no new ProductId references in the bytecode, so at runtime your ProductId will be represented as a String.

Note that if you try to wrap a value class in a class which uses generics (e.g. Option, Either) then your value will get boxed. You can avoid this by creating a simple case class which is specialized for your value class. While the case class will get instantiated (since you can't wrap a value class with another value class) the underlying ProductId will still be represented as String at runtime.

score 1 · Accepted Answer · answered Dec 10 '14 at 01:27

The idiomatic approach is to make it a private val, now that you can.

The standard library, so far as standards go, prefers self.

implicit final class ArrowAssoc[A](private val self: A) extends AnyVal

There is also repr, recalling both the phrase "underlying runtime representation" from the scaladoc for AnyVal and the repr of collections.

class StringOps(override val repr: String) extends AnyVal with StringLike[String]

There's also a smattering of i and n.

Personally, I use the special identifier, YMMV.

Idiomatic approach to Scala Value Classes

2 Answers2