Collection Operations: Filtering

An introduction to the most important filtering operations: filter, take, drop, slice, distinct, 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.

Filtering

filter

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

Probably the most ubiquitous of all filtering functions, filter accepts a predicate and returns a List of all the elements for which the predicate returns true.

Example

There are a few useful variants of filter:

One is filterNot, which returns a List of elements for which the predicate returns false.

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

Example

Another is filterIsInstance, which takes a single generic parameter, and returns all elements that are of that type. It should be noted that this also narrows the type of the returned list.

inline fun <reified R> Iterable<*>.filterIsInstance(): List<R>

Example

A kind of combination of the previous to is filterNotNull(), which returns all non-null elements. Notice how the return type is constrained to a non-nullable one.

fun <T : Any> Iterable<T?>.filterNotNull(): List<T>

Example

As with many other collection operations, the *To and *Indexed variants of most of the previous functions are available if you need them.

Subranges

There are many functions that allow you to take a continous subsection of a list according to some criteria.

take, drop

fun <T> Iterable<T>.take(n: kotlin.Int): List<T>

fun <T> Iterable<T>.drop(n: kotlin.Int): List<T>

The take/drop functions return the first n elements of the list/return the list without the first n elements, respectively.

Example

There are a few useful variants:

One are the *Last variants, which do the same thing, but for the last n elements.

fun <T> List<T>.takeLast(n: Int): List<T>

fun <T> List<T>.dropLast(n: Int): List<T>

Example

Another are the *While variants, which do the same thing, but instead of taking/dropping a fixed amount of elements, they accept a predicate and take/drop elements while that predicate is true:

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

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

Example

You also have *LastWhile variants, which are the combination of the previous two.

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

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

slice

fun <T> List<T>.slice(indices: IntRange): List<T>

fun <T> List<T>.slice(indices: Iterable<Int>): List<T>

The slice function comes in two variants — one returns all the elements in a certain index range, while the other returns the elements at the specified indices. Both could be implemented in terms of filterIndexed.

Example

Miscellaneous

distinct, distinctBy

fun <T> Iterable<T>.distinct(): List<T>

inline fun <T, K> Iterable<T>.distinctBy(
    selector: (T) -> K
): List<T>

Returns a List with all duplicate elements removed. The distinctBy variant removes all elements for which selector returns the same value.

Example

Go back to Collection Operations: Transformations, jump to the Table of Contents, or continue to Collection Operations: Single Element Access.