Add samples for sequence building API.

js/js.libraries/src/core/generated/_ArraysJs.kt

@@ -12518,6 +12518,8 @@ public fun CharArray.asIterable(): Iterable<Char> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun <T> Array<out T>.asSequence(): Sequence<T> {
     if (isEmpty()) return emptySequence()
@@ -12526,6 +12528,8 @@ public fun <T> Array<out T>.asSequence(): Sequence<T> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun ByteArray.asSequence(): Sequence<Byte> {
     if (isEmpty()) return emptySequence()
@@ -12534,6 +12538,8 @@ public fun ByteArray.asSequence(): Sequence<Byte> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun ShortArray.asSequence(): Sequence<Short> {
     if (isEmpty()) return emptySequence()
@@ -12542,6 +12548,8 @@ public fun ShortArray.asSequence(): Sequence<Short> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun IntArray.asSequence(): Sequence<Int> {
     if (isEmpty()) return emptySequence()
@@ -12550,6 +12558,8 @@ public fun IntArray.asSequence(): Sequence<Int> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun LongArray.asSequence(): Sequence<Long> {
     if (isEmpty()) return emptySequence()
@@ -12558,6 +12568,8 @@ public fun LongArray.asSequence(): Sequence<Long> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun FloatArray.asSequence(): Sequence<Float> {
     if (isEmpty()) return emptySequence()
@@ -12566,6 +12578,8 @@ public fun FloatArray.asSequence(): Sequence<Float> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun DoubleArray.asSequence(): Sequence<Double> {
     if (isEmpty()) return emptySequence()
@@ -12574,6 +12588,8 @@ public fun DoubleArray.asSequence(): Sequence<Double> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun BooleanArray.asSequence(): Sequence<Boolean> {
     if (isEmpty()) return emptySequence()
@@ -12582,6 +12598,8 @@ public fun BooleanArray.asSequence(): Sequence<Boolean> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun CharArray.asSequence(): Sequence<Char> {
     if (isEmpty()) return emptySequence()

js/js.libraries/src/core/generated/_CollectionsJs.kt

@@ -2031,6 +2031,8 @@ public inline fun <T> Iterable<T>.asIterable(): Iterable<T> {
 
 /**
  * Creates a [Sequence] instance that wraps the original collection returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromCollection
  */
 public fun <T> Iterable<T>.asSequence(): Sequence<T> {
     return Sequence { this.iterator() }

libraries/stdlib/common/src/generated/_Arrays.kt

@@ -7143,46 +7143,64 @@ public header fun CharArray.asIterable(): Iterable<Char>
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public header fun <T> Array<out T>.asSequence(): Sequence<T>
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public header fun ByteArray.asSequence(): Sequence<Byte>
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public header fun ShortArray.asSequence(): Sequence<Short>
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public header fun IntArray.asSequence(): Sequence<Int>
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public header fun LongArray.asSequence(): Sequence<Long>
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public header fun FloatArray.asSequence(): Sequence<Float>
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public header fun DoubleArray.asSequence(): Sequence<Double>
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public header fun BooleanArray.asSequence(): Sequence<Boolean>
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public header fun CharArray.asSequence(): Sequence<Char>
 

libraries/stdlib/common/src/generated/_Collections.kt

@@ -1041,6 +1041,8 @@ public header inline fun <T> Iterable<T>.asIterable(): Iterable<T>
 
 /**
  * Creates a [Sequence] instance that wraps the original collection returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromCollection
  */
 public header fun <T> Iterable<T>.asSequence(): Sequence<T>
 

libraries/stdlib/samples/test/samples/collections/collections.kt

@@ -18,7 +18,6 @@ package samples.collections
 
 import samples.*
 import kotlin.test.*
-import java.util.*
 
 
 @RunWith(Enclosed::class)

libraries/stdlib/samples/test/samples/collections/maps.kt

@@ -3,7 +3,6 @@ package samples.collections
 import samples.*
 import kotlin.test.*
 import java.util.*
-import kotlin.comparisons.*
 
 @RunWith(Enclosed::class)
 class Maps {

libraries/stdlib/samples/test/samples/collections/sequences.kt

@@ -0,0 +1,144 @@
+package samples.collections
+
+import samples.*
+import kotlin.test.*
+import kotlin.coroutines.experimental.buildIterator
+import kotlin.coroutines.experimental.buildSequence
+
+@RunWith(Enclosed::class)
+class Sequences {
+    class Building {
+
+        @Sample
+        fun generateSequence() {
+            var count = 3
+
+            val sequence = generateSequence {
+                (count--).takeIf { it > 0 } // will return null, when value becomes non-positive,
+                                            // and that will terminate the sequence
+            }
+
+            assertPrints(sequence.toList(), "[3, 2, 1]")
+
+            // sequence.forEach {  }  // <- iterating that sequence second time will fail
+        }
+
+        @Sample
+        fun generateSequenceWithSeed() {
+
+            fun fibonacci(): Sequence<Int> {
+                // fibonacci terms
+                // 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181, 6765, 10946, ...
+                return generateSequence(Pair(0, 1), { Pair(it.second, it.first + it.second) }).map { it.first }
+            }
+
+            assertPrints(fibonacci().take(10).toList(), "[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]")
+        }
+
+        @Sample
+        fun generateSequenceWithLazySeed() {
+            class LinkedValue<T>(val value: T, val next: LinkedValue<T>? = null)
+
+            fun <T> LinkedValue<T>?.asSequence(): Sequence<LinkedValue<T>> = generateSequence(
+                    seedFunction = { this },
+                    nextFunction = { it.next }
+            )
+
+            fun <T> LinkedValue<T>?.valueSequence(): Sequence<T> = asSequence().map { it.value }
+
+            val singleItem = LinkedValue(42)
+            val twoItems = LinkedValue(24, singleItem)
+
+            assertPrints(twoItems.valueSequence().toList(), "[24, 42]")
+            assertPrints(singleItem.valueSequence().toList(), "[42]")
+            assertPrints(singleItem.next.valueSequence().toList(), "[]")
+        }
+
+        @Sample
+        fun sequenceOfValues() {
+            val sequence = sequenceOf("first", "second", "last")
+            sequence.forEach(::println)
+        }
+
+        @Sample
+        fun sequenceFromCollection() {
+            val collection = listOf('a', 'b', 'c')
+            val sequence = collection.asSequence()
+
+            assertPrints(sequence.joinToString(), "a, b, c")
+        }
+
+        @Sample
+        fun sequenceFromArray() {
+            val array = arrayOf('a', 'b', 'c')
+            val sequence = array.asSequence()
+
+            assertPrints(sequence.joinToString(), "a, b, c")
+        }
+
+        @Sample
+        fun sequenceFromIterator() {
+            val array = arrayOf(1, 2, 3)
+
+            // create a sequence with a function, returning an iterator
+            val sequence1 = Sequence { array.iterator() }
+            assertPrints(sequence1.joinToString(), "1, 2, 3")
+            assertPrints(sequence1.drop(1).joinToString(), "2, 3")
+
+            // create a sequence from an existing iterator
+            // can be iterated only once
+            val sequence2 = array.iterator().asSequence()
+            assertPrints(sequence2.joinToString(), "1, 2, 3")
+            // sequence2.drop(1).joinToString() // <- iterating sequence second time will fail
+        }
+
+        @Sample
+        fun buildFibonacciSequence() {
+            fun fibonacci() = buildSequence {
+                var terms = Pair(0, 1)
+
+                // this sequence is infinite
+                while(true) {
+                    yield(terms.first)
+                    terms = Pair(terms.second, terms.first + terms.second)
+                }
+            }
+
+            assertPrints(fibonacci().take(10).toList(), "[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]")
+        }
+
+        @Sample
+        fun buildSequenceYieldAll() {
+            val sequence = buildSequence {
+                val start = 0
+                // yielding a single value
+                yield(start)
+                // yielding an iterable
+                yieldAll(1..5 step 2)
+                // yielding an infinite sequence
+                yieldAll(generateSequence(8) { it * 3 })
+            }
+
+            assertPrints(sequence.take(7).toList(), "[0, 1, 3, 5, 8, 24, 72]")
+        }
+
+        @Sample
+        fun buildIterator() {
+            val collection = listOf(1, 2, 3)
+            val wrappedCollection = object : AbstractCollection<Any>() {
+                override val size: Int = collection.size + 2
+
+                override fun iterator(): Iterator<Any> = buildIterator {
+                    yield("first")
+                    yieldAll(collection)
+                    yield("last")
+                }
+            }
+
+            assertPrints(wrappedCollection, "[first, 1, 2, 3, last]")
+        }
+
+    }
+
+
+}

libraries/stdlib/src/generated/_Arrays.kt

@@ -12599,6 +12599,8 @@ public fun CharArray.asIterable(): Iterable<Char> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun <T> Array<out T>.asSequence(): Sequence<T> {
     if (isEmpty()) return emptySequence()
@@ -12607,6 +12609,8 @@ public fun <T> Array<out T>.asSequence(): Sequence<T> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun ByteArray.asSequence(): Sequence<Byte> {
     if (isEmpty()) return emptySequence()
@@ -12615,6 +12619,8 @@ public fun ByteArray.asSequence(): Sequence<Byte> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun ShortArray.asSequence(): Sequence<Short> {
     if (isEmpty()) return emptySequence()
@@ -12623,6 +12629,8 @@ public fun ShortArray.asSequence(): Sequence<Short> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun IntArray.asSequence(): Sequence<Int> {
     if (isEmpty()) return emptySequence()
@@ -12631,6 +12639,8 @@ public fun IntArray.asSequence(): Sequence<Int> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun LongArray.asSequence(): Sequence<Long> {
     if (isEmpty()) return emptySequence()
@@ -12639,6 +12649,8 @@ public fun LongArray.asSequence(): Sequence<Long> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun FloatArray.asSequence(): Sequence<Float> {
     if (isEmpty()) return emptySequence()
@@ -12647,6 +12659,8 @@ public fun FloatArray.asSequence(): Sequence<Float> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun DoubleArray.asSequence(): Sequence<Double> {
     if (isEmpty()) return emptySequence()
@@ -12655,6 +12669,8 @@ public fun DoubleArray.asSequence(): Sequence<Double> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun BooleanArray.asSequence(): Sequence<Boolean> {
     if (isEmpty()) return emptySequence()
@@ -12663,6 +12679,8 @@ public fun BooleanArray.asSequence(): Sequence<Boolean> {
 
 /**
  * Creates a [Sequence] instance that wraps the original array returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromArray
  */
 public fun CharArray.asSequence(): Sequence<Char> {
     if (isEmpty()) return emptySequence()

libraries/stdlib/src/generated/_Collections.kt

@@ -2041,6 +2041,8 @@ public inline fun <T> Iterable<T>.asIterable(): Iterable<T> {
 
 /**
  * Creates a [Sequence] instance that wraps the original collection returning its elements when being iterated.
+ * 
+ * @sample samples.collections.Sequences.Building.sequenceFromCollection
  */
 public fun <T> Iterable<T>.asSequence(): Sequence<T> {
     return Sequence { this.iterator() }

libraries/stdlib/src/kotlin/collections/Sequences.kt

@@ -7,6 +7,8 @@ package kotlin.sequences
  * Given an [iterator] function constructs a [Sequence] that returns values through the [Iterator]
  * provided by that function.
  * The values are evaluated lazily, and the sequence is potentially infinite.
+ *
+ * @sample samples.collections.Sequences.Building.sequenceFromIterator
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> Sequence(crossinline iterator: () -> Iterator<T>): Sequence<T> = object : Sequence<T> {
@@ -15,6 +17,8 @@ public inline fun <T> Sequence(crossinline iterator: () -> Iterator<T>): Sequenc
 
 /**
  * Creates a sequence that returns all elements from this iterator. The sequence is constrained to be iterated only once.
+ *
+ * @sample samples.collections.Sequences.Building.sequenceFromIterator
  */
 public fun <T> Iterator<T>.asSequence(): Sequence<T> = Sequence { this }.constrainOnce()
 
@@ -27,6 +31,8 @@ public inline fun<T> java.util.Enumeration<T>.asSequence(): Sequence<T> = this.i
 
 /**
  * Creates a sequence that returns the specified values.
+ *
+ * @sample samples.collections.Sequences.Building.sequenceOfValues
  */
 public fun <T> sequenceOf(vararg elements: T): Sequence<T> = if (elements.isEmpty()) emptySequence() else elements.asSequence()
 
@@ -552,6 +558,9 @@ private class ConstrainedOnceSequence<T>(sequence: Sequence<T>) : Sequence<T> {
  * The returned sequence is constrained to be iterated only once.
  *
  * @see constrainOnce
+ * @see kotlin.coroutines.experimental.buildSequence
+ *
+ * @sample samples.collections.Sequences.Building.generateSequence
  */
 public fun <T : Any> generateSequence(nextFunction: () -> T?): Sequence<T> {
     return GeneratorSequence(nextFunction, { nextFunction() }).constrainOnce()
@@ -565,6 +574,10 @@ public fun <T : Any> generateSequence(nextFunction: () -> T?): Sequence<T> {
  * If [seed] is `null`, an empty sequence is produced.
  *
  * The sequence can be iterated multiple times, each time starting with [seed].
+ *
+ * @see kotlin.coroutines.experimental.buildSequence
+ *
+ * @sample samples.collections.Sequences.Building.generateSequenceWithSeed
  */
 @kotlin.internal.LowPriorityInOverloadResolution
 public fun <T : Any> generateSequence(seed: T?, nextFunction: (T) -> T?): Sequence<T> =
@@ -581,6 +594,10 @@ public fun <T : Any> generateSequence(seed: T?, nextFunction: (T) -> T?): Sequen
  * If [seedFunction] returns `null`, an empty sequence is produced.
  *
  * The sequence can be iterated multiple times.
+ *
+ * @see kotlin.coroutines.experimental.buildSequence
+ *
+ * @sample samples.collections.Sequences.Building.generateSequenceWithLazySeed
  */
 public fun <T: Any> generateSequence(seedFunction: () -> T?, nextFunction: (T) -> T?): Sequence<T> =
         GeneratorSequence(seedFunction, nextFunction)

libraries/stdlib/src/kotlin/coroutines/experimental/SequenceBuilder.kt

@@ -21,13 +21,20 @@ package kotlin.coroutines.experimental
 import kotlin.coroutines.experimental.intrinsics.*
 
 /**
- *  Builds a [Sequence] lazily yielding values one by one.
+ * Builds a [Sequence] lazily yielding values one by one.
+ *
+ * @see kotlin.sequences.generateSequence
+ *
+ * @sample samples.collections.Sequences.Building.buildSequenceYieldAll
+ * @sample samples.collections.Sequences.Building.buildFibonacciSequence
  */
 @SinceKotlin("1.1")
 public fun <T> buildSequence(builderAction: suspend SequenceBuilder<T>.() -> Unit): Sequence<T> = Sequence { buildIterator(builderAction) }
 
 /**
  * Builds an [Iterator] lazily yielding values one by one.
+ *
+ * @sample samples.collections.Sequences.Building.buildIterator
  */
 @SinceKotlin("1.1")
 public fun <T> buildIterator(builderAction: suspend SequenceBuilder<T>.() -> Unit): Iterator<T> {
@@ -38,12 +45,21 @@ public fun <T> buildIterator(builderAction: suspend SequenceBuilder<T>.() -> Uni
 
 /**
  * Builder for a [Sequence] or an [Iterator], provides [yield] and [yieldAll] suspension functions.
+ *
+ * @see buildSequence
+ * @see buildIterator
+ *
+ * @sample samples.collections.Sequences.Building.buildSequenceYieldAll
+ * @sample samples.collections.Sequences.Building.buildFibonacciSequence
  */
 @RestrictsSuspension
 @SinceKotlin("1.1")
 public abstract class SequenceBuilder<in T> internal constructor() {
     /**
      * Yields a value to the [Iterator] being built.
+     *
+     * @sample samples.collections.Sequences.Building.buildSequenceYieldAll
+     * @sample samples.collections.Sequences.Building.buildFibonacciSequence
      */
     public abstract suspend fun yield(value: T)
 
@@ -51,11 +67,15 @@ public abstract class SequenceBuilder<in T> internal constructor() {
      * Yields all values from the `iterator` to the [Iterator] being built.
      *
      * The sequence of values returned by the given iterator can be potentially infinite.
+     *
+     * @sample samples.collections.Sequences.Building.buildSequenceYieldAll
      */
     public abstract suspend fun yieldAll(iterator: Iterator<T>)
 
     /**
      * Yields a collections of values to the [Iterator] being built.
+     *
+     * @sample samples.collections.Sequences.Building.buildSequenceYieldAll
      */
     public suspend fun yieldAll(elements: Iterable<T>) {
         if (elements is Collection && elements.isEmpty()) return
@@ -66,6 +86,8 @@ public abstract class SequenceBuilder<in T> internal constructor() {
      * Yields potentially infinite sequence of values  to the [Iterator] being built.
      *
      * The sequence can be potentially infinite.
+     *
+     * @sample samples.collections.Sequences.Building.buildSequenceYieldAll
      */
     public suspend fun yieldAll(sequence: Sequence<T>) = yieldAll(sequence.iterator())
 }

libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt

@@ -29,7 +29,13 @@ fun sequences(): List<GenericFunction> {
 
     templates add f("asSequence()") {
         include(CharSequences, Maps)
-        doc { f -> "Creates a [Sequence] instance that wraps the original ${f.collection} returning its ${f.element.pluralize()} when being iterated." }
+        doc { f ->
+            """
+            Creates a [Sequence] instance that wraps the original ${f.collection} returning its ${f.element.pluralize()} when being iterated.
+
+            ${if (f in listOf(ArraysOfPrimitives, ArraysOfObjects, Iterables)) "@sample samples.collections.Sequences.Building.sequenceFrom${f.doc.collection.capitalize()}" else ""}
+            """
+        }
         returns("Sequence<T>")
         body { f ->
             """