Kotlin's firstNotNullOfOrNull – mouthful, but useful

[robinpokorny]

I explore Kotlin built-in methods by scrolling through the list of autocomplete options I get in the IDE.

One time, on a List, I noticed this weirdly named method firstNotNullOfOrNull. I had to re-read it to understand the parts. It sure sounds funny. I read about it a bit and yesterday, I finally had a chance to use it.

The actual function is quite nice and handy. Let's go by the parts.

1. first

The function first either returns the first element in the List, that is if it is called without arguments. Or you can pass a predicate, in which case it returns the first matching element.

val numbers = listOf(1, 2, 3, 4, 5)

numbers.first()
// -> 1

numbers.first { it % 2 == 0 }
// -> 2

With the predicate, it's almost the same as a function you might know: find. The only difference is that first throws if it does not find any matching element, while find returns null. There is an alias to find called findOrNull.

2. firstNotNullOf

This is an extension of finding an element by predicate, but instead it returns the first non-null value. So for element you do not care about, you return null and for the one you care about you return some value. This value then gets returned as the result of firstNotNullOf method call. For example, the value can be something that was needed to determine which element is important.

In the following, I find the first point that is more than 10 units from the origin and return that distance. So I save some computation.

val points: List<Point> = listOf(…)

points.firstNotNullOf {
    val distToOrigin = sqrt(it.x*it.x + it.y*it.y)

    if (distToOrigin < 10) null else distToOrigin
} 

Here, again, if no such element is found, the system throws an error. I do not generally like that. Fortunately, there is our good old method:

3. firstNotNullOfOrNull

The method firstNotNullOfOrNull will find the first element for which the callback returns something else than null and return that. In the case it does not find such element, it returns null itself.

I hope it is now clear why I like this method so much. And while it saved only a line or two, it feels like a good addition to the language. I also appreciate that the consistent naming is kept.

Links:

• firstNotNullOfOrNull in Kotlin docs
• Article Kotlin ❤ #2: firstNotNullOfOrNull, or how to merge 3 methods in one