List is the most popular type of built-in collection in Kotlin. Index access to the elements of lists provides a powerful set of operations for lists.
Retrieve elements by index
Lists support all common operations for element retrieval:
last(), and others listed in Retrieve single elements. What is specific for lists is index access to the elements, so the simplest way to read an element is retrieving it by index. That is done with the
get() function with the index passed in the argument or the shorthand
If the list size is less than the specified index, an exception is thrown. There are two other functions that help you avoid such exceptions:
getOrElse()lets you provide the function for calculating the default value to return if the index isn't present in the collection.
nullas the default value.
Retrieve list parts
In addition to common operations for Retrieving Collection Parts, lists provide the
subList() function that returns a view of the specified elements range as a list. Thus, if an element of the original collection changes, it also changes in the previously created sublists and vice versa.
Find element positions
In any lists, you can find the position of an element using the functions
lastIndexOf(). They return the first and the last position of an element equal to the given argument in the list. If there are no such elements, both functions return
There is also a pair of functions that take a predicate and search for elements matching it:
indexOfFirst()returns the index of the first element matching the predicate or
-1if there are no such elements.
indexOfLast()returns the index of the last element matching the predicate or
-1if there are no such elements.
Binary search in sorted lists
There is one more way to search elements in lists – binary search. It works significantly faster than other built-in search functions but requires the list to be sorted in ascending order according to a certain ordering: natural or another one provided in the function parameter. Otherwise, the result is undefined.
To search an element in a sorted list, call the
binarySearch() function passing the value as an argument. If such an element exists, the function returns its index; otherwise, it returns
(-insertionPoint - 1) where
insertionPoint is the index where this element should be inserted so that the list remains sorted. If there is more than one element with the given value, the search can return any of their indices.
You can also specify an index range to search in: in this case, the function searches only between two provided indices.
Comparator binary search
When list elements aren't
Comparable, you should provide a
Comparator to use in the binary search. The list must be sorted in ascending order according to this
Comparator. Let's have a look at an example:
Here's a list of
Product instances that aren't
Comparable and a
Comparator that defines the order: product
p1 precedes product
p1's price is less than
p2's price. So, having a list sorted ascending according to this order, we use
binarySearch() to find the index of the specified
Custom comparators are also handy when a list uses an order different from natural one, for example, a case-insensitive order for
Comparison binary search
Binary search with comparison function lets you find elements without providing explicit search values. Instead, it takes a comparison function mapping elements to
Int values and searches for the element where the function returns zero. The list must be sorted in the ascending order according to the provided function; in other words, the return values of comparison must grow from one list element to the next one.
Both comparator and comparison binary search can be performed for list ranges as well.
List write operations
In addition to the collection modification operations described in Collection write operations, mutable lists support specific write operations. Such operations use the index to access elements to broaden the list modification capabilities.
To add elements to a specific position in a list, use
addAll() providing the position for element insertion as an additional argument. All elements that come after the position shift to the right.
Lists also offer a function to replace an element at a given position -
set() and its operator form
set() doesn't change the indexes of other elements.
fill() simply replaces all the collection elements with the specified value.
To remove an element at a specific position from a list, use the
removeAt() function providing the position as an argument. All indices of elements that come after the element being removed will decrease by one.
In Collection Ordering, we describe operations that retrieve collection elements in specific orders. For mutable lists, the standard library offers similar extension functions that perform the same ordering operations in place. When you apply such an operation to a list instance, it changes the order of elements in that exact instance.
The in-place sorting functions have similar names to the functions that apply to read-only lists, but without the
asReversed() called on a mutable list returns another mutable list which is a reversed view of the original list. Changes in that view are reflected in the original list. The following example shows sorting functions for mutable lists: