Option & Null Safety

In Java, every reference may be null, and nothing in a method’s signature says whether it will return one. The classic failure is a NullPointerException far away from the place where the null was introduced. Scala 3 keeps null for Java interoperability (it is the only value of type Null), but idiomatic Scala code does not use it. The Scala 3 Book’s functional programming chapter avoids null entirely and offers Option as the replacement.

The idea is to move the absence from a runtime surprise to the static type. A method that may not find a value returns Option[Trail], and the caller cannot reach the Trail without deciding what to do about the empty case. A method that always finds one returns Trail, and there is nothing to check. The types are the documentation.

Source: Scala 3 Book: Using Option to replace null

Option[A] is a container with at most one element. It has exactly two shapes:

In the standard library Option is a sealed abstract class that is covariant in its type parameter (Option[+A]), Some is a final case class that extends Option[A], and None is a case object that extends Option[Nothing]. Because Nothing is a subtype of every type and Option is covariant, the single value None conforms to Option[Trail], Option[Int] and every other option type. See Variance for why this works, and Case Classes for what Some gets for free.

Because Option is sealed, the compiler knows these are the only two cases and checks pattern matches over it for exhaustivity.

There are three ways to create an option:

The first program defines a lookup that returns an Option and uses it with a pattern match and with map and flatMap.

Source: Scala 3 Book: Using Option/Some/None

findTrail is the idiomatic replacement for a Java method that would return null for an unknown name. The caller cannot ignore the result: the only way to get a Trail out of an Option[Trail] is to say what happens when there is none. A pattern match is the most explicit way to do it, and the compiler would warn if the None case were missing.

map applies a function to the value if there is one, and keeps None as None. flatMap is the same, but for a function that itself returns an option; it avoids the nested Option[Option[String]] that map would produce. The expression findTrail("Ridge").flatMap(_.hut) reads "the hut of the Ridge trail, if both the trail and its hut exist", and the third and fourth lines show it producing None as soon as either step has no value, with no explicit null check anywhere.

Sooner or later you need a plain value. The options, from safest to least safe:

The next program shows each of them, including the laziness of the default value.

Source: Scala 3 Book: Using a match expression and Scala API: Option

The first getOrElse printed "computing default for Lake" because the trail has no hut, while the second did not, because Ridge has one and the by-name default is never evaluated. If the default is expensive to compute, or has a side effect, that laziness is exactly what you want.

An Option supports the same vocabulary as a collection with at most one element, which is why most code that handles optional values looks like code that handles lists:

Each of them is exercised in the next program.

Source: Scala 3 Book: Thinking of Option as a container and Scala API: Option

forall returning true for None (the fifth line) surprises people the first time. It follows the logic definition: a universally quantified statement over an empty set holds. If you mean "present and satisfies", use exists.

Two of these deserve a closer look because they connect Option to the collections. toList turns an option into a collection, so findTrail("Ridge").toList ++ findTrail("Nope").toList concatenates the values that exist. The reverse direction is flatMap or flatten on a collection of options: List(Some(1), None, Some(3)).flatten drops the None entries, and List("1", "x", "3").flatMap(_.toIntOption) parses all the strings and keeps the ones that were valid numbers. This works because the collection’s flatMap accepts any function that returns an IterableOnce, and Option is one. For the collection side see Collection Operations.

A for comprehension over options stops at the first None. The compiler rewrites it into flatMap and map calls, so it needs nothing beyond the methods listed above. Each generator x <- opt unwraps one value; the comprehension as a whole yields an Option.

Source: Scala 3 Book: Using a for expression and Scala 3 Book: Control Structures

The first comprehension succeeds only because all four generators produce a value. The second one stops at the hut step because the Lake trail has no hut, and the whole expression is None. The for ... do form (the third block) runs its body only when every generator has a value, which makes it the safe version of if (x != null && y != null). The if guard in the last block calls withFilter, and Option provides it, so a guard turns a Some into None when the condition fails. The generator and guard rules, pattern generators and the case form are explained in For Comprehensions.

One limit worth knowing now: a comprehension mixes only one kind of container. You cannot put an Option generator and a List generator in the same for without converting one of them. Section Pitfalls shows the error.

Values that come from Java can be null, and Option.apply is the boundary conversion. Wrap every Java return value that may be null the moment it enters Scala code, and keep Option from then on.

Scala also interoperates with java.util.Optional. The conversions live in scala.jdk.OptionConverters: toScala turns an Optional into an Option, and toJava goes the other way. They are extension methods, so the import is required.

Source: Scala API: OptionConverters

Without the import the extension methods are not found:

Source: Scala API: OptionConverters

For Java’s own Optional API see Java Optional. It is closer to Scala’s Option than it looks: map, flatMap, filter, orElse and isPresent correspond to map, flatMap, filter, getOrElse and isDefined. A difference worth noting is that Optional is intended mainly for return types and cannot hold null as a value, while Some(null) is a perfectly valid Scala value.

Some(null) is a Some. Some.apply does not look at its argument, so Some(null) is a non-empty option holding null, and so is Some(x).map(_ => null). The null then appears when you use the value. Use Option(x) at every boundary where null is possible.

Source: Scala API: Option

The second line printed null, not fallback, because map wrapped the null in a Some, and getOrElse is only consulted for None. The third line used flatMap with Option(...) and therefore reached the fallback. The last lines show that Option is a collection of zero or one element: it has a size, an iterator, and a List.flatMap accepts it.

The same mistake produces a NullPointerException when the value is used:

Source: Scala API: Option

An Option and a List do not mix in a for or in flatMap on the option. Option.flatMap needs a function that returns an Option:

Source: Scala API: Option

Convert one side first (opt.toList, or list.headOption) or start the comprehension from the collection, whose flatMap accepts an option.

Do not call get, and do not compare to None with == to guard a get. If you wrote if opt.isDefined then opt.get, you wanted opt.foreach, opt.map or opt.fold. The compiler cannot tie the test and the get together, so a later edit can separate them silently.

Pattern matching on the content, not the wrapper. A pattern such as case Some(Trail(n, _, Some(h))) matches the option and the trail and the nested option in one step. Prefer that to a match that unwraps one layer at a time.

Option makes absence explicit for the code you write, but it does nothing for null coming from Java, and nothing stops a val hut: String = null in Scala code. Scala 3 has an opt-in mode that closes the gap by changing the type system: explicit nulls.

Explicit nulls is enabled with the compiler option -Yexplicit-nulls. In the Scala 3 reference the feature is listed under experimental definitions, and the -Y prefix marks an advanced option, so treat it as a feature you opt into knowingly, not as a default of the language. It is available on 3.3 LTS, 3.9 LTS and 3.10; the rules for Java types differ between 3.3 and later versions (see Scala 3.3 LTS versus 3.9 and 3.10).

In Scala CLI the option is a directive in the file (//> using option -Yexplicit-nulls). In sbt it goes into the compiler options of the project:

Source: Scala 3 Reference: Explicit Nulls

The two mechanisms address the same problem from different angles.

Use Option by default. Switch on explicit nulls when a lot of your code calls into Java and you want the compiler to find the unchecked results. The two work together: Option(x) accepts a T | Null, and a library can expose Option while using nullable types internally.

The Option examples in the first half of the page gave identical output on 3.3.8, 3.9.0 and 3.10.0 (except for the line numbers in a stack trace). The explicit nulls examples differ. This table lists the differences seen when the same programs were compiled on each version:

Practical consequence: on the 3.3 LTS the strict rules force a lot of .nn and Option(...) around Java calls, and match-based narrowing does not work. If you are adopting explicit nulls, do it on 3.9 or later.

The reference page also shows a head[T](xs: java.util.List[T]): T = xs.get(0) example inside unsafeNulls that is said not to compile. In the test used for this page it did compile on 3.9.0 and 3.10.0, printing Alto, so add a .nn only if your compiler asks for it. This is an example of documentation that has fallen a little behind the compiler.