From e7d250b7d76f671e764eeb8ef269946d58637e5d Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Mon, 1 Aug 2016 20:09:46 +0300 Subject: [PATCH] Document that sequences could be iterated multiple times. #KT-13115 Fixed --- libraries/stdlib/src/kotlin/collections/Sequence.kt | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/libraries/stdlib/src/kotlin/collections/Sequence.kt b/libraries/stdlib/src/kotlin/collections/Sequence.kt index ccc5b182095..5ac63d3354d 100644 --- a/libraries/stdlib/src/kotlin/collections/Sequence.kt +++ b/libraries/stdlib/src/kotlin/collections/Sequence.kt @@ -4,11 +4,20 @@ package kotlin.sequences * A sequence that returns values through its iterator. The values are evaluated lazily, and the sequence * is potentially infinite. * + * Sequences can be iterated multiple times, however some sequence implementations might constrain themselves + * to be iterated only once. That is mentioned specifically in their documentation (e.g. [generateSequence] overload). + * The latter sequences throw an exception on an attempt to iterate them the second time. + * + * Sequence operations, like [Sequence.map], [Sequence.filter] etc, generally preserve that property of a sequence, and + * again it's documented for an operation if it doesn't. + * * @param T the type of elements in the sequence. */ public interface Sequence { /** - * Returns an iterator that returns the values from the sequence. + * Returns an [Iterator] that returns the values from the sequence. + * + * Throws an exception if the sequence is constrained to be iterated once and `iterator` is invoked the second time. */ public operator fun iterator(): Iterator }