Collection Operations: Single Element Access

An introduction to the most important functions for single element access: find, first, last, indexOf, lastIndexOf, single, and their variants.

— — — — — — — — — — — — — — —

THE CURRENT VERSION OF THIS ARTICLE IS PUBLISHED HERE.

— — — — — — — — — — — — — — —

Tags: #FYI++

This article is part of the Kotlin Primer, an opinionated guide to the Kotlin language, which is indented to help facilitate Kotlin adoption inside Java-centric organizations. It was originally written as an organizational learning resource for Etnetera a.s. and I would like to express my sincere gratitude for their support.

It is recommended to read the Introduction before moving on. Check out the Table of Contents for all articles.

find

inline fun <T> Iterable<T>.find(predicate: (T) -> Boolean): T?

The find function searches for the first element satisfying a predicate and returns it. If no such element is found, it returns null.

Example

There is also the findLast variant, which returns the last element satisfying a predicate, or null.

inline fun <T> Iterable<T>.findLast(predicate: (T) -> Boolean): T?

Example

first, last

fun <T> List<T>.first(): T

fun <T> List<T>.last(): T

The first/last functions return, as you would expect, the first/last elements of a list. When the list is empty, they throw a NoSuchElementException.

Example

There are a couple of useful variants.

One variant accepts a predicate, and returns the first/last element satisfying that predicate, or throws NoSuchElementException if no such element is found.

inline fun <T> Iterable<T>.first(predicate: (T) -> Boolean): T

inline fun <T> Iterable<T>.last(predicate: (T) -> Boolean): T

Example:

The *OrNull variants return null instead of throwing when run on an empty list.

fun <T> List<T>.firstOrNull(): T?

fun <T> List<T>.lastOrNull(): T?

inline fun <T> Iterable<T>.firstOrNull(predicate: (T) -> Boolean): T

inline fun <T> Iterable<T>.lastOrNull(predicate: (T) -> Boolean): T

Finally, firstNotNullOf and firstNotNullOfOrNull apply a transformation to each element, and return the first result which is not null. The former throws NoSuchElementException if no such element is found, while the latter returns null.

inline fun <T, R : Any> Iterable<T>.firstNotNullOf(
    transform: (T) -> R?
): R

inline fun <T, R : Any> Iterable<T>.firstNotNullOfOrNull(
    transform: (T) -> R?
): R?

Example

indexOf, lastIndexOf

fun <T> Iterable<T>.indexOf(element: T): Int

fun <T> Iterable<T>.lastIndexOf(element: T): Int

Returns the index of the first/last occurrence of element, or -1 if no such element is found.

The related indexOfFirst/indexOfLast methods accepts a predicate and return the index of the first/last element that satisfies it.

inline fun <T> Iterable<T>.indexOfFirst(
    predicate: (T) -> Boolean
): Int

inline fun <T> Iterable<T>.indexOfLast(
    predicate: (T) -> Boolean
): Int

Example

single

fun <T> Iterable<T>.single(): T

An interesting function that returns the single element of a list if it only contains a single element, and throws otherwise.

Example

There are a few variations:

One variation accepts a predicate, and returns the element satisfying it if there is precisely one, and throws otherwise.

fun <T> Iterable<T>.single(predicate: (T) -> Boolean): T

Example

There are also *OrNull variants for both of the above, which return null instead of throwing.

fun <T> Iterable<T>.singleOrNull(): T?

fun <T> Iterable<T>.singleOrNull(predicate: (T) -> Boolean): T?

Go back to Collection Operations: Filtering, jump to the Table of Contents, or continue to Collection Operations: Predicates.