List Specific Operations

    Lists support all common operations for element retrieval: elementAt(), first(), last(), and others listed in Retrieving 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 function with the index passed in the argument or the shorthand [index] syntax.

    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.
    • returns null as the default value.

    In addition to common operations for Retrieving Collection Parts, lists provide the 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.

    1. fun main() {
    2. //sampleStart
    3.     val numbers = (0..13).toList()
    4.     println(numbers.subList(3, 6))
    5. //sampleEnd
    6. }

    In any lists, you can find the position of an element using the functions indexOf() and . 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 -1.

    1. fun main() {
    2. //sampleStart
    3.     val numbers = listOf(1, 2, 3, 4, 2, 5)
    4.     println(numbers.indexOf(2))
    5.     println(numbers.lastIndexOf(2))
    6. //sampleEnd
    7. }

    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 -1 if there are no such elements.
    • returns the index of the last element matching the predicate or -1 if there are no such elements.
    1. fun main() {
    2. //sampleStart
    3.     val numbers = mutableListOf(1, 2, 3, 4)
    4.     println(numbers.indexOfFirst { it > 2})
    5.     println(numbers.indexOfLast { it % 2 == 1})
    6. //sampleEnd
    7. }

    Binary search in sorted lists

    There is one more way to search elements in lists – . 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.

    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:

    1. data class Product(val name: String, val price: Double)
    3. fun main() {
    4.     val productList = listOf(
    5.         Product("WebStorm", 49.0),
    6.         Product("AppCode", 99.0),
    7.         Product("DotTrace", 129.0),
    8.         Product("ReSharper", 149.0))
    10.     println(productList.binarySearch(Product("AppCode", 99.0), compareBy<Product> { it.price }.thenBy { it.name }))
    11. //sampleEnd
    12. }

    Here’s a list of Product instances that aren’t Comparable and a Comparator that defines the order: product p1 precedes product p2 if 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 Product.

    Custom comparators are also handy when a list uses an order different from natural one, for example, a case-insensitive order for String elements.

    1. fun main() {
    2. //sampleStart
    3.     val colors = listOf("Blue", "green", "ORANGE", "Red", "yellow")
    4.     println(colors.binarySearch("RED", String.CASE_INSENSITIVE_ORDER)) // 3
    5. //sampleEnd
    6. }

    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.

    1. import kotlin.math.sign
    2. //sampleStart
    3. data class Product(val name: String, val price: Double)
    5. fun priceComparison(product: Product, price: Double) = sign(product.price - price).toInt()
    7. fun main() {
    8.     val productList = listOf(
    9.         Product("WebStorm", 49.0),
    10.         Product("AppCode", 99.0),
    11.         Product("DotTrace", 129.0),
    12.         Product("ReSharper", 149.0))
    14.     println(productList.binarySearch { priceComparison(it, 99.0) })
    15. }
    16. //sampleEnd

    Both comparator and comparison binary search can be performed for list ranges as well.

    To add elements to a specific position in a list, use add() and providing the position for element insertion as an additional argument. All elements that come after the position shift to the right.

    Updating

    Lists also offer a function to replace an element at a given position - and its operator form []. set() doesn’t change the indexes of other elements.

    1. fun main() {
    2. //sampleStart
    3.     val numbers = mutableListOf("one", "five", "three")
    4.     numbers[1] =  "two"
    5.     println(numbers)
    6. //sampleEnd
    7. }

    fill() simply replaces all the collection elements with the specified value.

    1. fun main() {
    3.     numbers.fill(3)
    4.     println(numbers)
    5. //sampleEnd
    6. }

    To remove an element at a specific position from a list, use the function providing the position as an argument. All indices of elements that come after the element being removed will decrease by one.

    1. fun main() {
    2. //sampleStart
    3.     val numbers = mutableListOf(1, 2, 3, 4, 3)    
    4.     numbers.removeAt(1)
    5.     println(numbers)
    6. //sampleEnd
    7. }

    For removing the first and the last element, there are handy shortcuts removeFirst() and . Note that on empty lists, they throw an exception. To receive null instead, use removeFirstOrNull() and

    Sorting

    In , 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.

    • sort* instead of sorted* in the names of all sorting functions: sort(), , sortBy(), and so on.
    • instead of shuffled().
    • reverse() instead of reversed().

    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:

    1. fun main() {
    2. //sampleStart
    3.     val numbers = mutableListOf("one", "two", "three", "four")
    5.     numbers.sort()
    6.     println("Sort into ascending: $numbers")
    7.     numbers.sortDescending()
    8.     println("Sort into descending: $numbers")
    10.     numbers.sortBy { it.length }
    11.     println("Sort into ascending by length: $numbers")
    12.     numbers.sortByDescending { it.last() }
    13.     println("Sort into descending by the last letter: $numbers")
    15.     numbers.sortWith(compareBy<String> { it.length }.thenBy { it })
    16.     println("Sort by Comparator: $numbers")
    18.     numbers.shuffle()
    19.     println("Shuffle: $numbers")
    21.     numbers.reverse()
    22.     println("Reverse: $numbers")
    23. //sampleEnd