From 60cafc662381d61852b44dd110bd4c327b4d3478 Mon Sep 17 00:00:00 2001 From: Abduqodiri Qurbonzoda Date: Fri, 2 Jun 2023 16:33:43 +0300 Subject: [PATCH] Document the exceptions Iterator throws --- core/builtins/native/kotlin/Iterator.kt | 21 +++++++++++++++++++ .../src/kotlin/collections/Iterator.kt | 21 +++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/core/builtins/native/kotlin/Iterator.kt b/core/builtins/native/kotlin/Iterator.kt index d854a6a66f9..8c5918c7825 100644 --- a/core/builtins/native/kotlin/Iterator.kt +++ b/core/builtins/native/kotlin/Iterator.kt @@ -23,6 +23,8 @@ package kotlin.collections public interface Iterator { /** * Returns the next element in the iteration. + * + * @throws NoSuchElementException if the iteration has no next element. */ public operator fun next(): T @@ -39,6 +41,9 @@ public interface Iterator { public interface MutableIterator : Iterator { /** * Removes from the underlying collection the last element returned by this iterator. + * + * @throws IllegalStateException if [next] has not been called yet, + * or the most recent [next] call has already been followed by a [remove] call. */ public fun remove(): Unit } @@ -59,16 +64,22 @@ public interface ListIterator : Iterator { /** * Returns the previous element in the iteration and moves the cursor position backwards. + * + * @throws NoSuchElementException if the iteration has no previous element. */ public fun previous(): T /** * Returns the index of the element that would be returned by a subsequent call to [next]. + * + * Returns collection size if the iteration is at the end of the collection. */ public fun nextIndex(): Int /** * Returns the index of the element that would be returned by a subsequent call to [previous]. + * + * Returns -1 if the iteration is at the beginning of the collection. */ public fun previousIndex(): Int } @@ -76,6 +87,7 @@ public interface ListIterator : Iterator { /** * An iterator over a mutable collection that supports indexed access. Provides the ability * to add, modify and remove elements while iterating. + * @see MutableList.listIterator */ public interface MutableListIterator : ListIterator, MutableIterator { // Query Operations @@ -83,10 +95,19 @@ public interface MutableListIterator : ListIterator, MutableIterator { override fun hasNext(): Boolean // Modification Operations + /** + * Removes from the underlying collection the last element returned by this iterator. + * + * @throws IllegalStateException if neither [next] nor [previous] has not been called yet, + * or the most recent [next] or [previous] call has already been followed by a [remove] or [add] call. + */ override fun remove(): Unit /** * Replaces the last element returned by [next] or [previous] with the specified element [element]. + * + * @throws IllegalStateException if neither [next] nor [previous] has not been called yet, + * or the most recent [next] or [previous] call has already been followed by a [remove] or [add] call. */ public fun set(element: T): Unit diff --git a/libraries/stdlib/native-wasm/src/kotlin/collections/Iterator.kt b/libraries/stdlib/native-wasm/src/kotlin/collections/Iterator.kt index 274a682945c..b11590fa37c 100644 --- a/libraries/stdlib/native-wasm/src/kotlin/collections/Iterator.kt +++ b/libraries/stdlib/native-wasm/src/kotlin/collections/Iterator.kt @@ -12,6 +12,8 @@ package kotlin.collections public interface Iterator { /** * Returns the next element in the iteration. + * + * @throws NoSuchElementException if the iteration has no next element. */ public operator fun next(): T @@ -28,6 +30,9 @@ public interface Iterator { public interface MutableIterator : Iterator { /** * Removes from the underlying collection the last element returned by this iterator. + * + * @throws IllegalStateException if [next] has not been called yet, + * or the most recent [next] call has already been followed by a [remove] call. */ public fun remove(): Unit } @@ -48,16 +53,22 @@ public interface ListIterator : Iterator { /** * Returns the previous element in the iteration and moves the cursor position backwards. + * + * @throws NoSuchElementException if the iteration has no previous element. */ public fun previous(): T /** * Returns the index of the element that would be returned by a subsequent call to [next]. + * + * Returns collection size if the iteration is at the end of the collection. */ public fun nextIndex(): Int /** * Returns the index of the element that would be returned by a subsequent call to [previous]. + * + * Returns -1 if the iteration is at the beginning of the collection. */ public fun previousIndex(): Int } @@ -65,6 +76,7 @@ public interface ListIterator : Iterator { /** * An iterator over a mutable collection that supports indexed access. Provides the ability * to add, modify and remove elements while iterating. + * @see MutableList.listIterator */ public interface MutableListIterator : ListIterator, MutableIterator { // Query Operations @@ -72,10 +84,19 @@ public interface MutableListIterator : ListIterator, MutableIterator { override fun hasNext(): Boolean // Modification Operations + /** + * Removes from the underlying collection the last element returned by this iterator. + * + * @throws IllegalStateException if neither [next] nor [previous] has not been called yet, + * or the most recent [next] or [previous] call has already been followed by a [remove] or [add] call. + */ override fun remove(): Unit /** * Replaces the last element returned by [next] or [previous] with the specified element [element]. + * + * @throws IllegalStateException if neither [next] nor [previous] has not been called yet, + * or the most recent [next] or [previous] call has already been followed by a [remove] or [add] call. */ public fun set(element: T): Unit