kotlin-stdlib/kotlin.collections/ArrayList/listIterator

listIterator

expect open override fun listIterator(): MutableListIterator<E>(source)

Returns a list iterator over the elements in this list (in proper sequence).

If the list needs to be iterated starting from a specific index, a listIterator overload accepting the Int parameter could be used instead of using this function and manually iterating until the required index is reached.

Since Kotlin

1.0

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   val list = listOf('a', 'b')
val iterator = list.listIterator()

// "Cursor" is at the beginning of the list,
// so there is no previous element, only a next one
println("iterator.hasPrevious() is ${iterator.hasPrevious()}") // false
println("iterator.hasNext() is ${iterator.hasNext()}") // true

// Let's scan the list in a forward direction
println(iterator.next()) // a
println(iterator.next()) // b

// Cursor is past the end of the list,
// so there is no next element, only a previous one
println("iterator.hasPrevious() is ${iterator.hasPrevious()}") // true
println("iterator.hasNext() is ${iterator.hasNext()}") // false

// Let's scan the list backwards, starting from the end
println(iterator.previous()) // b
println(iterator.previous()) // a

// We ran out of elements
// iterator.previous() // will fail with NoSuchElementException

// Empty list has an empty iterator
val emptyListIterator = emptyList<String>().listIterator()
println("emptyListIterator.hasNext() is ${emptyListIterator.hasNext()}") // false
println("emptyListIterator.hasPrevious() is ${emptyListIterator.hasPrevious()}") // false 
   //sampleEnd
}
expect open override fun listIterator(index: Int): MutableListIterator<E>(source)

Returns a list iterator over the elements in this list (in proper sequence), starting at the specified index.

Since Kotlin

1.0

Throws

if index is less than zero or greater than size of this list.

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   val list = listOf('a', 'b', 'c')

// The iterator will scan elements starting from 'c' (the element at the index = 2)
val sublistIterator = list.listIterator(index = 2)
// However, previous elements are also accessible
println("sublistIterator.hasPrevious() is ${sublistIterator.hasPrevious()}") // true
// One step forward
println(sublistIterator.next()) // c
// Two steps backward
println(sublistIterator.previous()) // c
println(sublistIterator.previous()) // b

// If the index is equal to the length of the list,
// the iterator's "cursor" will point past the last element and only previous elements
// will be accessible
val pastLastIterator = list.listIterator(index = 3)
println("pastLastIterator.hasPrevious() is ${pastLastIterator.hasPrevious()}") // true
println("pastLastIterator.hasNext() is ${pastLastIterator.hasNext()}") // false
println(pastLastIterator.previous()) // c
println(pastLastIterator.previous()) // b

// It's an error to use indices outside of list bounds
// list.listIterator(-1) // will fail with IndexOutOfBoundsException
// list.listIterator(list.size + 1) // will fail with IndexOutOfBoundsException 
   //sampleEnd
}
actual open override fun listIterator(): MutableListIterator<E>(source)

Returns a list iterator over the elements in this list (in proper sequence).

If the list needs to be iterated starting from a specific index, a listIterator overload accepting the Int parameter could be used instead of using this function and manually iterating until the required index is reached.

Since Kotlin

1.3

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   val list = listOf('a', 'b')
val iterator = list.listIterator()

// "Cursor" is at the beginning of the list,
// so there is no previous element, only a next one
println("iterator.hasPrevious() is ${iterator.hasPrevious()}") // false
println("iterator.hasNext() is ${iterator.hasNext()}") // true

// Let's scan the list in a forward direction
println(iterator.next()) // a
println(iterator.next()) // b

// Cursor is past the end of the list,
// so there is no next element, only a previous one
println("iterator.hasPrevious() is ${iterator.hasPrevious()}") // true
println("iterator.hasNext() is ${iterator.hasNext()}") // false

// Let's scan the list backwards, starting from the end
println(iterator.previous()) // b
println(iterator.previous()) // a

// We ran out of elements
// iterator.previous() // will fail with NoSuchElementException

// Empty list has an empty iterator
val emptyListIterator = emptyList<String>().listIterator()
println("emptyListIterator.hasNext() is ${emptyListIterator.hasNext()}") // false
println("emptyListIterator.hasPrevious() is ${emptyListIterator.hasPrevious()}") // false 
   //sampleEnd
}
actual open override fun listIterator(index: Int): MutableListIterator<E>(source)

Returns a list iterator over the elements in this list (in proper sequence), starting at the specified index.

Since Kotlin

1.3

Throws

if index is less than zero or greater than size of this list.

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   val list = listOf('a', 'b', 'c')

// The iterator will scan elements starting from 'c' (the element at the index = 2)
val sublistIterator = list.listIterator(index = 2)
// However, previous elements are also accessible
println("sublistIterator.hasPrevious() is ${sublistIterator.hasPrevious()}") // true
// One step forward
println(sublistIterator.next()) // c
// Two steps backward
println(sublistIterator.previous()) // c
println(sublistIterator.previous()) // b

// If the index is equal to the length of the list,
// the iterator's "cursor" will point past the last element and only previous elements
// will be accessible
val pastLastIterator = list.listIterator(index = 3)
println("pastLastIterator.hasPrevious() is ${pastLastIterator.hasPrevious()}") // true
println("pastLastIterator.hasNext() is ${pastLastIterator.hasNext()}") // false
println(pastLastIterator.previous()) // c
println(pastLastIterator.previous()) // b

// It's an error to use indices outside of list bounds
// list.listIterator(-1) // will fail with IndexOutOfBoundsException
// list.listIterator(list.size + 1) // will fail with IndexOutOfBoundsException 
   //sampleEnd
}
actual open override fun listIterator(): MutableListIterator<E>(source)

Returns a list iterator over the elements in this list (in proper sequence).

If the list needs to be iterated starting from a specific index, a listIterator overload accepting the Int parameter could be used instead of using this function and manually iterating until the required index is reached.

Since Kotlin

1.8

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   val list = listOf('a', 'b')
val iterator = list.listIterator()

// "Cursor" is at the beginning of the list,
// so there is no previous element, only a next one
println("iterator.hasPrevious() is ${iterator.hasPrevious()}") // false
println("iterator.hasNext() is ${iterator.hasNext()}") // true

// Let's scan the list in a forward direction
println(iterator.next()) // a
println(iterator.next()) // b

// Cursor is past the end of the list,
// so there is no next element, only a previous one
println("iterator.hasPrevious() is ${iterator.hasPrevious()}") // true
println("iterator.hasNext() is ${iterator.hasNext()}") // false

// Let's scan the list backwards, starting from the end
println(iterator.previous()) // b
println(iterator.previous()) // a

// We ran out of elements
// iterator.previous() // will fail with NoSuchElementException

// Empty list has an empty iterator
val emptyListIterator = emptyList<String>().listIterator()
println("emptyListIterator.hasNext() is ${emptyListIterator.hasNext()}") // false
println("emptyListIterator.hasPrevious() is ${emptyListIterator.hasPrevious()}") // false 
   //sampleEnd
}
actual open override fun listIterator(index: Int): MutableListIterator<E>(source)

Returns a list iterator over the elements in this list (in proper sequence), starting at the specified index.

Since Kotlin

1.8

Throws

if index is less than zero or greater than size of this list.

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   val list = listOf('a', 'b', 'c')

// The iterator will scan elements starting from 'c' (the element at the index = 2)
val sublistIterator = list.listIterator(index = 2)
// However, previous elements are also accessible
println("sublistIterator.hasPrevious() is ${sublistIterator.hasPrevious()}") // true
// One step forward
println(sublistIterator.next()) // c
// Two steps backward
println(sublistIterator.previous()) // c
println(sublistIterator.previous()) // b

// If the index is equal to the length of the list,
// the iterator's "cursor" will point past the last element and only previous elements
// will be accessible
val pastLastIterator = list.listIterator(index = 3)
println("pastLastIterator.hasPrevious() is ${pastLastIterator.hasPrevious()}") // true
println("pastLastIterator.hasNext() is ${pastLastIterator.hasNext()}") // false
println(pastLastIterator.previous()) // c
println(pastLastIterator.previous()) // b

// It's an error to use indices outside of list bounds
// list.listIterator(-1) // will fail with IndexOutOfBoundsException
// list.listIterator(list.size + 1) // will fail with IndexOutOfBoundsException 
   //sampleEnd
}
actual open override fun listIterator(): MutableListIterator<E>(source)

Returns a list iterator over the elements in this list (in proper sequence).

If the list needs to be iterated starting from a specific index, a listIterator overload accepting the Int parameter could be used instead of using this function and manually iterating until the required index is reached.

Since Kotlin

1.8

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   val list = listOf('a', 'b')
val iterator = list.listIterator()

// "Cursor" is at the beginning of the list,
// so there is no previous element, only a next one
println("iterator.hasPrevious() is ${iterator.hasPrevious()}") // false
println("iterator.hasNext() is ${iterator.hasNext()}") // true

// Let's scan the list in a forward direction
println(iterator.next()) // a
println(iterator.next()) // b

// Cursor is past the end of the list,
// so there is no next element, only a previous one
println("iterator.hasPrevious() is ${iterator.hasPrevious()}") // true
println("iterator.hasNext() is ${iterator.hasNext()}") // false

// Let's scan the list backwards, starting from the end
println(iterator.previous()) // b
println(iterator.previous()) // a

// We ran out of elements
// iterator.previous() // will fail with NoSuchElementException

// Empty list has an empty iterator
val emptyListIterator = emptyList<String>().listIterator()
println("emptyListIterator.hasNext() is ${emptyListIterator.hasNext()}") // false
println("emptyListIterator.hasPrevious() is ${emptyListIterator.hasPrevious()}") // false 
   //sampleEnd
}
actual open override fun listIterator(index: Int): MutableListIterator<E>(source)

Returns a list iterator over the elements in this list (in proper sequence), starting at the specified index.

Since Kotlin

1.8

Throws

if index is less than zero or greater than size of this list.

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   val list = listOf('a', 'b', 'c')

// The iterator will scan elements starting from 'c' (the element at the index = 2)
val sublistIterator = list.listIterator(index = 2)
// However, previous elements are also accessible
println("sublistIterator.hasPrevious() is ${sublistIterator.hasPrevious()}") // true
// One step forward
println(sublistIterator.next()) // c
// Two steps backward
println(sublistIterator.previous()) // c
println(sublistIterator.previous()) // b

// If the index is equal to the length of the list,
// the iterator's "cursor" will point past the last element and only previous elements
// will be accessible
val pastLastIterator = list.listIterator(index = 3)
println("pastLastIterator.hasPrevious() is ${pastLastIterator.hasPrevious()}") // true
println("pastLastIterator.hasNext() is ${pastLastIterator.hasNext()}") // false
println(pastLastIterator.previous()) // c
println(pastLastIterator.previous()) // b

// It's an error to use indices outside of list bounds
// list.listIterator(-1) // will fail with IndexOutOfBoundsException
// list.listIterator(list.size + 1) // will fail with IndexOutOfBoundsException 
   //sampleEnd
}