Retrieve single elements
Kotlin collections provide a set of functions for retrieving single elements from collections. Functions described on this page apply to both lists and sets.
As the definition of list says, a list is an ordered collection. Hence, every element of a list has its position that you can use for referring. In addition to functions described on this page, lists offer a wider set of ways to retrieve and search for elements by indices. For more details, see List-specific operations.
In turn, set is not an ordered collection by definition. However, the Kotlin
Set stores elements in certain orders. These can be the order of insertion (in
LinkedHashSet), natural sorting order (in
SortedSet), or another order. The order of a set of elements can also be unknown. In such cases, the elements are still ordered somehow, so the functions that rely on the element positions still return their results. However, such results are unpredictable to the caller unless they know the specific implementation of
Retrieve by position
For retrieving an element at a specific position, there is the function
elementAt(). Call it with the integer number as an argument, and you'll receive the collection element at the given position. The first element has the position
0, and the last one is
(size - 1).
elementAt() is useful for collections that do not provide indexed access, or are not statically known to provide one. In case of
List, it's more idiomatic to use indexed access operator (
To avoid exceptions when retrieving element with non-existing positions, use safe variations of
elementAtOrNull()returns null when the specified position is out of the collection bounds.
elementAtOrElse()additionally takes a lambda function that maps an
Intargument to an instance of the collection element type. When called with an out-of-bounds position, the
elementAtOrElse()returns the result of the lambda on the given value.
Retrieve by condition
last() also let you search a collection for elements matching a given predicate. When you call
first() with a predicate that tests a collection element, you'll receive the first element on which the predicate yields
true. In turn,
last() with a predicate returns the last element matching it.
Use the aliases if their names suit your situation better:
Retrieve with selector
If you need to map the collection before retrieving the element, there is a function
firstNotNullOf(). It combines 2 actions:
Maps the collection with the selector function
Returns the first non-null value in the result
firstNotNullOf() throws the
NoSuchElementException if the resulting collection doesn't have a non-null element. Use the counterpart
firstNotNullOfOrNull() to return null in this case.
On empty collections,
random() throws an exception. To receive
null instead, use
Check element existence
To check the presence of an element in a collection, use the
contains() function. It returns
true if there is a collection element that
equals() the function argument. You can call
contains() in the operator form with the
To check the presence of multiple instances together at once, call
containsAll() with a collection of these instances as an argument.