Kotlin Sublist IndexOutOfBoundsException: Key Mistakes to Avoid

Handling lists and sublists in Kotlin can sometimes result in unexpected errors, particularly with the infamous "IndexOutOfBoundsException." This issue often arises when working with sublists, indices, and elements that are outside the list size or trying to perform structural changes. If you've encountered this error, don't worry—you’re not alone!

In this blog, we’ll explore the common pitfalls of using Kotlin’s sublist functionality, why this exception occurs, and how to avoid IndexOutOfBoundsException in your Kotlin code.

Understanding Kotlin Sublist and IndexOutOfBoundsException

A Kotlin Sublist IndexOutOfBoundsException occurs when you try to access indices of a list that are beyond its bounds. This is particularly common when you use functions like subList, slice, or access elements with an invalid index. Let's break down how sublists work and common issues that may cause this error.

How SubLists Work in Kotlin

In Kotlin, the subList function allows you to create a view of a portion of an original list using specified indices. The syntax for subList is as follows:

Copy
val list = listOf(1, 2, 3, 4, 5)
val sublist = list.subList(fromIndex, toIndex)

Here, fromIndex is inclusive, while toIndex is exclusive. For example, if you want to get a sublist from index 2 to 4, you would write:

Copy
val sublist = list.subList(2, 4) // Retrieves elements at indices 2 and 3 (4 is exclusive)

However, fromIndex and toIndex must be within the list size, or the function throws IndexOutOfBoundsException. Let's examine key errors to avoid when working with sublists.

Key Mistakes to Avoid with Kotlin Sublist IndexOutOfBoundsException

1. Using Out-of-Bounds Indices

One of the most common mistakes is providing indices that exceed the list size. For example, if your list has a size of 5 and you attempt to access a sublist using fromIndex or toIndex beyond this limit, the function throws IndexOutOfBoundsException.

Example: Out-of-Bounds Indices

Copy
val list = listOf(1, 2, 3, 4, 5)
val sublist = list.subList(4, 6) // Error: toIndex 6 is out of bounds

In this example, the toIndex of 6 is out of range for a list of size 5, resulting in an exception.

Fix: Always verify that both fromIndex and toIndex are within bounds. You can use list.size to validate this dynamically:

Copy
if (fromIndex >= 0 && toIndex <= list.size) {
    val sublist = list.subList(fromIndex, toIndex)
}

2. Mistakenly Using Structural Changes on a Sublist

A common misunderstanding is thinking that a sublist is independent of the original list. In reality, sublists are merely views of the original list. Any structural changes to the sublist (such as adding or removing elements) will impact the original list and vice versa.

Example: Structural Changes on Sublist

Copy
val list = mutableListOf(1, 2, 3, 4, 5)
val sublist = list.subList(1, 4)
sublist.add(6) // Throws UnsupportedOperationException

Here, sublist is a view of the original list, and since it’s immutable, attempting a structural change like add throws an exception.

Fix: If you need a modifiable version, consider creating a new list:

3. Confusing Slice and SubList

In Kotlin, both slice and subList can extract parts of a list, but they behave differently. slice is a safer option when dealing with invalid indices because it won’t throw an exception if you specify out-of-range indices.

Example of Slice Function

The slice function accepts a range, which avoids IndexOutOfBoundsException. Unlike subList, slice is safer if you need only specific elements and may have uncertain indices.

4. Modifying List Size During Iteration

If you make structural changes to the original list while iterating through a sublist, you’ll encounter unpredictable behavior and likely throw an exception. This happens because altering the original list affects the sublist’s bounds.

Example: Structural Changes During Iteration

Fix: Avoid modifying the original list while working with its sublist or create a new list if necessary.

5. Handling Empty or Null Lists

Using subList on an empty list or with invalid indices can lead to IndexOutOfBoundsException. If you need to handle cases where the sublist might be empty, use return emptyList() as a fallback.

Example: Handling Empty List

This example uses return emptyList() when the list size is less than the required indices, avoiding exceptions.

Code Examples and Best Practices to Avoid IndexOutOfBoundsException

Here are some practical examples to help you avoid IndexOutOfBoundsException while working with sublists:

Verify List Size Before Accessing Sublist

Always check the list size before specifying indices in subList.

Avoid Structural Changes on Immutable Sublists

If you need to modify a sublist, convert it into a new list to prevent errors.

Using Slice Instead of Sublist

If you’re unsure about the indices, use slice to avoid IndexOutOfBoundsException.

The Bottom Line!

The Kotlin Sublist IndexOutOfBoundsException can be tricky to handle, especially if you’re unfamiliar with the pitfalls of using sublists. By ensuring your indices are within the list size, avoiding structural changes on sublists, and considering alternatives like the slice function, you can prevent this common error. Following these practices not only avoids frustrating exceptions but also keeps your code clean, predictable, and robust.

val newList = list.subList(1, 4).toMutableList()
newList.add(6) // Works without error

val list = listOf(1, 2, 3, 4, 5)
val sliced = list.slice(1..3) // Returns [2, 3, 4]

val list = mutableListOf(1, 2, 3, 4, 5)
val sublist = list.subList(1, 4)
list.add(6) // Changes original list's structure
println(sublist) // May throw View Undefined Exception

val list = listOf<Int>()
val sublist = if (list.size >= 2) list.subList(0, 2) else emptyList()

val list = listOf(1, 2, 3, 4, 5)
val fromIndex = 1
val toIndex = 4

if (fromIndex >= 0 && toIndex <= list.size) {
    val sublist = list.subList(fromIndex, toIndex)
    println(sublist)
} else {
    println("Invalid indices for sublist.")
}

val list = listOf(1, 2, 3, 4, 5)
val mutableSublist = list.subList(1, 4).toMutableList()
mutableSublist.add(6) // Safe modification

val list = listOf(1, 2, 3, 4, 5)
val slicedList = list.slice(1..3) // Avoids out-of-bounds error